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:

src/content/docs/<category>/<article-slug>.mdx

Examples:

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:

---
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:

---
title: <Action-oriented title>
description: <One sentence summary for humans and agents.>
---

## 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 <MCP_API_TOKEN> or <account-id>.
• 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:

{
  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:

pnpm docs:index

The generated file is:

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:

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.