smolify-api-docs

# Smolify API Docs Turn an API implementation into accurate, reviewable documentation. The source of truth is the repository, not model memory. Write Markdown only; never emit runtime MDX, JSX, scripts, or unsanitized HTML. ## Preconditions 1. Confirm the current task uses GPT-5.6. If it does not, stop and ask the user to switch models before generation. 2. Read the repository's `AGENTS.md` and follow the closest applicable guidance. 3. Locate API evidence in this order: - OpenAPI/Swagger, GraphQL, protobuf, or RPC contracts - route/controller definitions - request and response schemas - authentication and authorization middleware - tests and fixtures - existing documentation and examples 4. Do not make network calls to the production API unless the user explicitly authorizes them and provides a safe test target. ## Workflow ### 1. Inventory Create a compact route inventory containing method, path, authentication, request schema, success response, error responses, and supporting source files. Flag conflicts between contracts, code, and tests instead of guessing. ### 2. Plan Propose a navigation tree. Prefer task-oriented guides plus a reference page per endpoint group. Ask for clarification only when a product decision materially changes the output; otherwise record the uncertainty in the generated page. ### 3. Generate Write `.smolify/smolify.bundle.json` matching `references/bundle.schema.json`. - Every page must contain useful prose, not placeholder sections. - Include runnable examples only when values are supported by code or fixtures. - Record supporting paths in `sourceFiles`. - Never include secrets copied from environment files, fixtures, logs, or code. - Use `generator.name = "codex"` and the exact active model identifier. - Use ISO 8601 UTC for `generatedAt`. ### 4. Validate Run: ```bash node <skill-directory>/scripts/validate.mjs .smolify/smolify.bundle.json ``` Fix every validation failure. Then review the generated git diff for leaked secrets, invented behavior, broken examples, duplicated slugs, and navigation entries without pages. ### 5. Publish Publishing changes external state. Do it only when the user explicitly asks to publish after reviewing the diff. Prefer the authenticated Smolify MCP tool `publish_docs` when it is available. The MCP client completes OAuth authorization-code + PKCE in the browser; never ask the user to paste its access or refresh token into chat. Pass the validated bundle and project slug to the tool, then report its deployment ID and URL. For headless CI or installations without the MCP, use the project-token fallback below. Require these environment variables: - `SMOLIFY_PUBLISH_TOKEN` — project-scoped token from the Smolify dashboard - `SMOLIFY_ENDPOINT` — optional; defaults to `https://app.smol.ly` - `SMOLIFY_PROJECT` — the project slug Then run: ```bash node <skill-directory>/scripts/publish.mjs .smolify/smolify.bundle.json ``` Never print the publish token. Report the deployment ID and public URL returned by the service. ## Updating existing docs When `.smolify/smolify.bundle.json` already exists, preserve unaffected prose and navigation. Use the git diff to determine which API surfaces changed, then update only impacted pages unless a broader rewrite is necessary for accuracy. ## Reviewing public Smolify projects When the user asks to review or improve public Smolify documentation: 1. Call `discover_public_projects` and choose the exact project. 2. If authenticated, call `whoami` once so the user can see whether the review will advance community status. Treat `officialPublisherName` returned by discovery as source provenance only, never as a security claim. 3. Call `search_docs` before `get_doc_page`; read bounded slices and inspect the public source repository when its URL is available. 4. Call `rate_docs` with the exact active GPT-5.6 model identifier and concise, evidence-grounded notes. 5. Propose an improvement only when you can produce a complete valid bundle. Preserve accurate unaffected content, cite supporting paths in `sourceFiles`, and call `propose_doc_improvement` with a clear summary and rationale. 6. Tell the user that the proposal is pending. Never describe a proposal as published; only the project owner can preview, accept, and activate it.