Problem
When an agent tries to use plotlink-ows features (e.g., update story metadata, upload cover image), there are no skill definitions, CLAUDE.md, or API docs available. The agent has to reverse-engineer endpoints by reading installed package source code under ~/.npm/_npx/.
From a real session — the agent had to:
- Hit
/api/health to confirm the server was running
- Find the login endpoint by trial
- Grep through
app/routes/ in the npm cache to find route definitions
- Read
publish.ts to get exact endpoint signatures
This took over 2 minutes of research for what should be a 5-second lookup.
Scope
Update CLAUDE.md at the package root to document the local API:
Auth
- How to authenticate (login endpoint, bearer token)
- Where the OWS passphrase lives
API Endpoints
POST /api/publish/upload-cover — file upload (form-data, max 500KB, WebP/JPEG), returns { cid }
POST /api/publish/update-storyline — fields: storylineId (required), coverCid, genre, language, isNsfw
POST /api/publish — full publish flow (storyline + plot)
GET /api/stories — list stories
- Any other routes in
app/routes/
Available genres / languages
- Reference to the valid values
Common workflows
- "Update cover image for story #N" (upload-cover → update-storyline)
- "Set genre and language for story #N"
- "Publish a new story"
Blocker
Acceptance Criteria
Refs: #180
Problem
When an agent tries to use plotlink-ows features (e.g., update story metadata, upload cover image), there are no skill definitions, CLAUDE.md, or API docs available. The agent has to reverse-engineer endpoints by reading installed package source code under
~/.npm/_npx/.From a real session — the agent had to:
/api/healthto confirm the server was runningapp/routes/in the npm cache to find route definitionspublish.tsto get exact endpoint signaturesThis took over 2 minutes of research for what should be a 5-second lookup.
Scope
Update
CLAUDE.mdat the package root to document the local API:Auth
API Endpoints
POST /api/publish/upload-cover— file upload (form-data, max 500KB, WebP/JPEG), returns{ cid }POST /api/publish/update-storyline— fields:storylineId(required),coverCid,genre,language,isNsfwPOST /api/publish— full publish flow (storyline + plot)GET /api/stories— list storiesapp/routes/Available genres / languages
Common workflows
Blocker
\r\nnewline corruption in multipart form-data. Skill docs should note this limitation until fixed.Acceptance Criteria
CLAUDE.mdupdated with local API endpoint docsRefs: #180