Explore what's in your spec

Four commands answer "what's in here?" without opening the editor. They're the fastest way to orient yourself in an unfamiliar spec, or to assert things about it from a script.

catalog

A smoke test of the whole spec, keyed by entity type. For each active type you get an object with its count (how many of that entity the spec holds), a one-line description of what the type is, and the MCP tools that operate on it — alongside the serializer version and the claude4spec version that wrote the spec. It's the fastest way to see a project's shape at a glance, or to assert on it in CI.

The result is grouped under types, one entry per entity type:

{
  "types": {
    "endpoint": {
      "count": 42,
      "version": "1.0",
      "description": "HTTP endpoints — the API surface of the system.",
      "mcpToolsLine": "create_endpoint, update_endpoint, …"
    }
  },
  "claude4spec": "1.0.15"
}

It deliberately stays cheap: counts and descriptions only, never schemas.

list-tags

Every tag used across the spec. Tags are how entities are grouped — by release, by area, by whatever convention your spec uses — so this is the vocabulary you'll pass to the tag-based commands.

list-slugs

Every slug of one entity type. Pair it with detail to walk through entities by hand, or feed the slugs into another command.

find-references

Where is an entity used? find-references walks your pages/ directory and reports every spot that mentions a given entity, with the page path, the kind of reference, and the line. Use it before you rename or remove something.

By default it reports only direct references. Add --include-tag-matches to also surface pages that pull the entity in dynamically through a tag query — those rows include a via field naming the tag(s) that matched.