Installation

← Guide index

Builds are downloaded straight from noop.co.jp. docs-kit is not published to any package manager.

Requirements

Nothing outside git is required. The only things docs-kit writes into your repository are docs/, docs.config.yaml, the CLAUDE.md managed block, and the generated CI and .claude/commands. It never performs git operations (commit, push, …).

1. Install a binary

macOS / Linux

curl -fsSL "https://downloads.noop.co.jp/docs-kit/latest/docs-kit_$(uname -s | tr A-Z a-z)_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar -xz && sudo install -m 755 docs-kit /usr/local/bin/

That builds the archive name from uname. To inspect before running, do it in steps.

echo "docs-kit_$(uname -s | tr A-Z a-z)_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz"

curl -fLO "https://downloads.noop.co.jp/docs-kit/latest/docs-kit_darwin_arm64.tar.gz"

tar -xzf docs-kit_darwin_arm64.tar.gz && sudo install -m 755 docs-kit /usr/local/bin/

Each archive holds four files: the docs-kit binary plus LICENSE, NOTICE and README.md. docs-kit is Apache-2.0, which requires NOTICE to travel with any redistribution (section 4(d)). Only the binary needs to go on your PATH.

Available archives:

Pinning a version

latest/ always points at the newest build. To fetch a specific version, put the version number in the path instead — those paths never change once published.

curl -fLO "https://downloads.noop.co.jp/docs-kit/v1.1.0/docs-kit_darwin_arm64.tar.gz"

Checksums

SHA-256 sums live in checksums.txt in the same directory.

curl -fLO "https://downloads.noop.co.jp/docs-kit/latest/checksums.txt" && shasum -a 256 -c checksums.txt --ignore-missing

Windows

Download docs-kit_windows_amd64.zip and put the extracted docs-kit.exe somewhere on your PATH.

curl.exe -fLO "https://downloads.noop.co.jp/docs-kit/latest/docs-kit_windows_amd64.zip"
mkdir $env:USERPROFILE\bin -Force
Expand-Archive docs-kit_windows_amd64.zip -DestinationPath $env:USERPROFILE\bin -Force
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\bin", "User")

macOS Gatekeeper

The binary is unsigned, so the first run may be blocked.

xattr -d com.apple.quarantine /usr/local/bin/docs-kit

2. Verify the install

docs-kit --version

docs-kit v1.1.0

docs-kit --help

docs-kit — a design-doc management tool for AI-assisted coding

Usage: docs-kit [-C <dir>] <command> [flags] [args]

Commands:
  init                Generate scaffolding + config + CLAUDE.md block + CI
  adopt               Add front matter stubs to existing docs (status: draft)
  lint                Validate front matter against the schema (exit 1 = errors)
  stale [id...]       Freshness check (exit 0=ok / 1=stale / 2=broken)
  index [--check]     Generate INDEX.md (--check verifies sync, for CI)
  which <path...>     Reverse lookup: path -> related documents
  new <layer> <slug>  Create a document from a template (--title)
  schema              Print the front matter schema (fields / enum / per-layer rules)
  verify <id...>      Update verified_at to HEAD and promote to current
  mcp                 Start the MCP server over stdio (docs_which / docs_stale / docs_verify / docs_new)

Flags:
  -C <dir>            Change the working directory (as git does)
  --format text|json  Output format for lint / stale / which / schema
  --version           Print the version

If that works, you are installed. Next: Project setup.

3. Upgrading and uninstalling

Upgrade — rerun the install and overwrite the binary. No config or document migration is needed.

curl -fsSL "https://downloads.noop.co.jp/docs-kit/latest/docs-kit_$(uname -s | tr A-Z a-z)_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar -xz && sudo install -m 755 docs-kit /usr/local/bin/

After upgrading, run docs-kit init again in each repository if you want the CLAUDE.md managed block refreshed to the current spec (idempotent; nothing outside the block is overwritten).

Uninstall — delete the binary.

sudo rm /usr/local/bin/docs-kit

docs/ and docs.config.yaml are plain Markdown and YAML, so you can leave them in place.

4. Installing in CI

docs-kit init generates .github/workflows/docs-kit.yml with the install steps included. Written by hand it looks like this:

- uses: actions/checkout@v4
  with:
    fetch-depth: 0        # stale needs the full history. required
- name: Install docs-kit
  run: |
    curl -fsSL "https://downloads.noop.co.jp/docs-kit/${DOCS_KIT_VERSION}/docs-kit_linux_amd64.tar.gz" | tar -xz
    sudo install -m 755 docs-kit /usr/local/bin/docs-kit
  env:
    DOCS_KIT_VERSION: v1.1.0
- run: docs-kit lint
- run: docs-kit stale
- run: docs-kit index --check

Two things matter here.

• fetch-depth: 0 is required. With a shallow clone the verified_at SHAs are not in history and every document comes back broken (unknown-sha)
• Pin the version. Using a versioned path such as v1.1.0/ instead of latest/ stops CI behaviour from shifting on every release

5. Register the MCP server with Claude Code

The CLI is self-sufficient, but wiring it up to the AI is where the effect changes qualitatively.

claude mcp add docs-kit -- docs-kit mcp

The registration points at docs-kit on your PATH. Replacing the binary therefore requires no re-registration — start a new session and the updated tool definitions are picked up.

Check the registration:

claude mcp list

Success looks like four tools (docs_which / docs_stale / docs_verify / docs_new) visible in the session.

Remove it:

claude mcp remove docs-kit

Starting it by hand to test

The MCP server speaks stdio, so you would not normally start it manually. But it validates the config and git before starting and exits 3 immediately if either is wrong, which makes it a decent smoke test.

docs-kit mcp

If it exits right away, the problem is on the repository side (no config, not a git repository, …). If it sits there producing no output, that is correct — stop it with Ctrl-C.

stdin / stdout are claimed as the MCP transport. Logs all go to stderr, one JSON line per call.

6. Troubleshooting

Next

• Project setup — set up a fresh repository
• Adopting in an existing project — bring in existing Markdown