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 <[e-mail]>
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
• environmentVariables reflect src/config/index.ts — server-specific required vars in both entries, transport vars only in HTTP entry
• Package entries cover supported distribution channels (npm stdio, npm http)

7. GitHub Repository Metadata

Sync the GitHub repo with package.json using gh. Skip if gh isn't available.

Description:

gh repo edit cyanheads/git-mcp-server --description "$(jq -r .description package.json)"

Topics ↔ Keywords:

Compare GitHub topics against package.json keywords. They should be the union — add any that exist in one but not the other.

gh repo view --json repositoryTopics -q '.repositoryTopics[].name'
jq -r '.keywords[]' package.json

• Missing from GitHub → gh repo edit --add-topic <topic>
• Missing from package.json → add to keywords array

Common keywords across MCP servers (mcp, mcp-server, model-context-protocol, typescript) should appear in both. Domain-specific keywords (git, version-control, branch, etc.) should also be present in both.

8. CHANGELOG.md

This repo uses a monolithic changelog in Keep a Changelog format. Conventions:

• Every release gets a top-level ## v<version> - <YYYY-MM-DD> header with a concrete version and date — never [Unreleased]
• Optional one-paragraph narrative intro right under the header
• Grouped sections: ### Added, ### Changed, ### Fixed, ### Removed, ### Security
• Breaking changes called out in bold at the top of the relevant section or with a dedicated ### Breaking header
• Entries reference tool names in code (`git_merge`), PR/issue numbers ((#42)), and user-visible commands
• Oldest releases at the bottom; newest at the top

Before shipping a release, verify the top entry is current, dated, and complete. Hand-editing is expected — no build step.

9. bunfig.toml

Verify bunfig.toml exists at the project root. Expected contents:

[install]
auto = "fallback"
frozenLockfile = false

[run]
bun = true

10. LICENSE

Confirm the LICENSE file exists and matches package.json license field (Apache-2.0).

11. docs/tree.md

Regenerate the directory structure:

bun run tree

Review the output for anything unexpected (leftover scaffolding files, missing directories, stray dist artifacts).

12. Final Verification

Run the full check suite one last time:

bun run devcheck
bun test

Both must pass clean.

Checklist

• Surface area audited — tool/resource/prompt/provider inventory built
• README.md accurate — tool tables, config, descriptions match actual code
• CLAUDE.md accurate — no stale content, real examples, structure matches reality; AGENTS.md symlink intact
• .env.example in sync with src/config/index.ts
• package.json metadata complete and versioned
• server.json schema + versions + env vars current; matches package.json
• GitHub repo description matches package.json; topics ↔ keywords in sync
• bunfig.toml present
• CHANGELOG.md has a concrete-dated entry for the release (Keep a Changelog format)
• LICENSE file present
• docs/tree.md regenerated
• bun run devcheck passes
• bun test passes