[#179] Add local API docs to CLAUDE.md

[realproject7]

Summary

• Added comprehensive local writer API documentation to CLAUDE.md covering:
  • Auth flow (passphrase setup, login, bearer tokens, where OWS passphrase lives)
  • Publish endpoints (upload-cover with WebP/JPEG support, update-storyline, full publish SSE flow)
  • Stories CRUD endpoints
  • Wallet, dashboard, and settings endpoints
  • Valid genre and language references (from lib/genres.ts)
  • Common workflows for cover update, metadata update, and publishing
• Bumped version to 1.0.28

Fixes #179

Test plan

• Verify CLAUDE.md renders correctly in GitHub
• Confirm all documented endpoints match actual route files
• Check genre/language lists match lib/genres.ts

🤖 Generated with Claude Code

[realproject7]

@re2 REQUEST CHANGES

Two minor issues:

1. Genre count off by one: docs say "Genres (22)" but lib/genres.ts has 21 entries (count them — Others is the 21st). Should be Genres (21).

2. Missing endpoint: POST /api/stories/:name/:file/mark-not-indexed exists in app/routes/stories.ts but is not listed in the Stories table.

Otherwise the docs are thorough and accurate — endpoints, auth flow, workflows, and language list all check out.

[project7-interns]

Verdict: REQUEST CHANGES

Summary

The new section covers the main auth and publishing workflows, but it does not yet satisfy the issue scope of documenting the local API without source-code lookup. Several existing app route endpoints are missing, and one auth/passphrase storage detail is inaccurate.

Findings

• [medium] CLAUDE.md says the OWS passphrase is stored hashed in ~/.plotlink-ows/.env, but the auth route writes the raw passphrase as OWS_PASSPHRASE and hashes it only for comparison.

  • File: CLAUDE.md:39
  • Suggestion: Reword this to say the passphrase is stored in ~/.plotlink-ows/.env as OWS_PASSPHRASE and is used to decrypt/sign with the OWS wallet. Avoid claiming the env value is hashed.

• [medium] The docs omit existing API routes, so an agent still has to inspect source for part of app/routes/.

  • File: CLAUDE.md:72
  • Suggestion: Add the missing POST /api/stories/:name/:file/mark-not-indexed endpoint from app/routes/stories.ts, and add a Terminal section for app/routes/terminal.ts endpoints such as POST /api/terminal/spawn, GET /api/terminal/session/:storyName, GET /api/terminal/status, POST /api/terminal/rename, POST /api/terminal/stop, DELETE /api/terminal/:storyName, and DELETE /api/terminal/:storyName/discard. The issue explicitly asks for other app/routes/ endpoints, and the PR currently documents wallet/dashboard/settings but skips terminal entirely.

Decision

Requesting changes because the docs are intended as agent-facing API reference material; inaccurate secret-storage wording and missing route coverage undermine the acceptance criteria. I did not identify problems with the WebP/JPEG upload documentation or the 1.0.28 patch bump.

[realproject7]

@re2 APPROVE — Both issues fixed. Genre count corrected to 21, mark-not-indexed endpoint added. Docs are accurate and comprehensive. LGTM.

[project7-interns]

Verdict: APPROVE

Summary

The requested documentation fixes are in place: the passphrase storage wording no longer says the env value is hashed, the missing stories endpoint is listed, and terminal/WebSocket routes are now documented. lint-and-typecheck passed on the latest head.

Findings

• None.

Decision

Approving. The added CLAUDE.md API reference now satisfies issue #179 closely enough for agents to discover auth, publish, stories, terminal, wallet, dashboard, and settings workflows without reading route source.