# Add an SOP article ## Purpose Use this SOP when a task is complete and the user asks for a documentation article about the work. The goal is to create documentation that helps humans operate the system and helps AI agents retrieve the right context later through the private MCP endpoint. ## When to use this Create or update an SOP article when: - A feature, integration, deployment flow, operational process, or recurring fix was completed. - The task produced steps that should be repeatable. - The user explicitly asks to document the work. - Future agents would benefit from knowing what was changed, why, and how to validate it. Do not create an SOP article for trivial edits, temporary debugging notes, secrets, credentials, one-off local environment details, or incomplete experiments. ## Required article qualities Every SOP article must be: - Specific to GETQUICK systems and actual repository state. - Safe to share internally without exposing secrets or private tokens. - Written for both human operators and AI agents. - Actionable enough that another engineer or agent can repeat the process. - Indexed by the MCP docs search by running `pnpm docs:index`. ## File location and naming Create documentation under `src/content/docs`. Use a category directory and kebab-case filename: ```text src/content/docs//.mdx ``` Examples: ```text src/content/docs/getquick/create-a-private-mcp.mdx src/content/docs/agents/add-an-sop-article.mdx ``` If the article belongs to a new category, add the category to `astro.config.mjs` under the Starlight `sidebar` configuration. ## Frontmatter template Every article must start with frontmatter: ```mdx --- title: Clear action-oriented title description: One sentence describing when and why to use this SOP. --- ``` Use a title that describes the procedure, not the implementation detail. Prefer `Create a private MCP` over `MCP endpoint changes`. ## Article template Use this structure by default: ```mdx --- title: description: --- ## Purpose Explain what this SOP helps someone do and when they should use it. ## Context Describe the relevant system, repository, service, domain, or user workflow. Include only facts needed to understand the procedure. ## Outcome List the expected final state after the procedure is complete. ## Steps Give ordered, repeatable steps. Include commands when useful. ## Validation List checks that prove the work succeeded. Include expected outputs or HTTP statuses when helpful. ## Operational notes for agents Tell future AI agents how to use this article. Mention the key MCP search terms, follow-up docs, and decision rules. ## Troubleshooting List likely failure modes and how to resolve them. ``` ## Writing rules - Do not include production secrets, API tokens, passwords, private keys, session cookies, or customer-sensitive data. - Replace sensitive values with placeholders such as `` or ``. - Prefer exact commands and paths over vague descriptions. - Use fenced code blocks with a language label when possible. - Keep prose direct and procedural. - Mention validation steps and expected results. - Add operational notes for agents so MCP retrieval is useful. - If the article documents a Cloudflare deployment, include the relevant Wrangler commands and Cloudflare dashboard steps. ## Updating navigation Add the article to the Starlight sidebar in `astro.config.mjs`. Example: ```js { label: 'Agents', items: [ { label: 'Add an SOP article', slug: 'agents/add-an-sop-article' }, ], } ``` If the category already exists, append the article to the existing `items` array. ## Updating the MCP index Regenerate the docs index after adding or editing SOP content: ```bash pnpm docs:index ``` The generated file is: ```text src/generated/docs-index.json ``` Commit this file with the article so AI agents can search the latest documentation. ## Build validation Run the production build: ```bash pnpm build ``` The build must pass before committing. It verifies: - Starlight content schema. - MDX syntax. - Sidebar slug validity. - Generated routes. - Cloudflare Worker bundle output. ## Commit checklist Before committing, verify: - The article is under the correct category directory. - `astro.config.mjs` includes the sidebar entry. - `src/generated/docs-index.json` includes the new article. - `pnpm build` passes. - No secrets or local-only values were added. Then commit the article, sidebar change, and regenerated index together. ## Operational notes for agents When documenting completed work, search existing SOPs first to avoid duplicates. If a related article exists, update it instead of creating a new one. Use search terms from the completed task in the article title, description, headings, and validation section. This improves retrieval through `search_docs`. If the user asks for a documentation article, create the article, regenerate the MCP index, run the build, and summarize the changed files. ## Troubleshooting - If the build fails with a sidebar slug error, confirm the slug matches the file path without the extension. - If the build fails with frontmatter errors, confirm the article has valid `title` and `description` fields. - If the MCP search does not find the new article, rerun `pnpm docs:index`. - If generated index content looks incomplete, check for unusual MDX syntax that the index generator may strip.