/polish-docs-meta

name: polish-docs-meta
description: >
  Finalize documentation and project metadata for a ship-ready release. Use after implementation is complete, tests pass, and devcheck is clean. Safe to run at any stage — each step checks current state and only acts on what still needs work.
metadata:
  author: cyanheads
  version: '1.0'
  type: workflow

When to Use

• Implementation is functionally complete (tools, resources, prompts, providers all working)
• `bun run devcheck` passes, `bun test` passes
• Preparing for a release, or making surface-area changes that affect README/metadata
• User says "polish", "polish docs", "finalize", "make it ship-ready", "clean up docs", or similar
• Re-running after adding/removing tools, resources, or other surface area changes

Prefer running after implementation is complete, but safe to re-run at any point — steps are idempotent.

Prerequisites

• [ ] Tools/resources/prompts implemented and registered
• [ ] `bun run devcheck` passes
• [ ] `bun test` passes

If these aren't met, address them first.

Steps

1. Audit the Surface Area

Read the registered definitions. Build a mental model of what the server actually exposes — names, descriptions, input/output shapes, auth scopes. This inventory drives every document below.

Read:

• `src/mcp-server/tools/definitions/index.ts` (the `allToolDefinitions` barrel)
• Every `src/mcp-server/tools/definitions/git-*.tool.ts`
• `src/mcp-server/resources/definitions/index.ts`
• `src/mcp-server/resources/definitions/git-working-directory.resource.ts`
• `src/mcp-server/prompts/definitions/index.ts`
• `src/mcp-server/prompts/definitions/git-wrapup.prompt.ts`
• `src/config/index.ts` (Zod config schema)
• `src/services/git/core/IGitProvider.ts` (provider contract)

Capture: tool count (expected ~29), resource count, prompt count, git provider capabilities, required env vars.

2. README.md

Compare README content against the audit. Update tool/resource/prompt tables, env var lists, badges, and descriptions to match actual surface area. Don't rewrite sections that are already accurate.

Specific sync points:

• Version badge reflects `package.json` version
• Tool count in any feature-summary block matches actual count
• The tools table lists every registered tool with a one-line description pulled from `TOOL_DESCRIPTION`
• Config section lists every env var defined in `src/config/index.ts` with current defaults
• Links to external deps (`[Hono](https://hono.dev/)`, `[MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)`, etc.) are on first mention
• Transport examples (stdio + http) are current

3. Agent Protocol (CLAUDE.md / AGENTS.md)

`AGENTS.md` is a symlink to `CLAUDE.md` — edit only `CLAUDE.md`.

Review against reality:

• Tool/resource count and file structure claims match the actual codebase
• Directory table in section II reflects what's actually in `src/`
• Code examples use real current APIs (`createToolHandler`, `ToolLogicDependencies`, `IGitProvider`) — not outdated signatures
• If new subsystems were added (e.g., a new provider, new storage backend), the structure diagram in section V is updated
• Checklist in section XIV still covers everything a contributor needs to verify
• Version at the top matches `package.json` version

Keep the diff minimal — change what's stale, leave what's accurate.

4. `.env.example`

Compare `.env.example` against the `src/config/index.ts` Zod schema. Add any missing vars with a comment and default. Remove vars for features that no longer exist. Group by category (Transport, Auth, Storage, Git, Telemetry) matching the schema's layout.

Categories to cover:

• **Transport:** `MCP_TRANSPORT_TYPE`, `MCP_HTTP_PORT`, `MCP_HTTP_HOST`, `MCP_HTTP_PATH`
• **Auth:** `MCP_AUTH_MODE`, `MCP_AUTH_SECRET_KEY`, `OAUTH_ISSUER_URL`, `OAUTH_AUDIENCE`, `OAUTH_JWKS_URI`
• **Storage:** `STORAGE_PROVIDER_TYPE`, `STORAGE_FILESYSTEM_PATH`
• **Git:** `GIT_PROVIDER`, `GIT_SIGN_COMMITS`, `GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`, `GIT_COMMITTER_EMAIL`, `GIT_BASE_DIR`, `GIT_MAX_COMMAND_TIMEOUT_MS`, `GIT_MAX_BUFFER_SIZE_MB`, `GIT_WRAPUP_INSTRUCTIONS_PATH`
• **Telemetry:** `OTEL_ENABLED`, `OTEL_SERVICE_NAME`, `OTEL_SERVICE_VERSION`, `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`

5. `package.json` Metadata

Check for empty or placeholder fields. Key fields:

| Field | Source of truth | | :--------------- | :-------------------------------------------------------- | | `description` | Canonical — every other surface derives from it | | `version` | Semver, matches `server.json` and `CHANGELOG.md` headline | | `mcpName` | Reverse-domain: `io.github.cyanheads/git-mcp-server` | | `repository.url` | `git+https://github.com/cyanheads/git-mcp-server.git` | | `bugs.url` | `https://github.com/cyanheads/git-mcp-server/issues` | | `homepage` | `https://github.com/cyanheads/git-mcp-server#readme` | | `keywords` | Union with GitHub topics (see step 7) | | `engines` | `bun >=1.2.0`, `node >=20.0.0` | | `packageManager` | Pinned bun version | | `author` | `cyanheads <casey@caseyjhand.com>` | | `license` | `Apache-2.0` |

**`description` is the canonical source.** Every other surface (README header, `server.json`, GitHub repo description) derives from it. Write it here first, then propagate.

6. `server.json`

Diff against current state and update stale fields. Key sync points:

• `$schema` set to the current MCP server manifest schema URL
• `name` matches `mcpName` from `package.json`
• `version` matches `package.json` version (in all places: top-level + each `packages[].version`)
• `description` matches `package.json` description
• `environmentVar