@inharness-ai/claude4spec 1.0.0

package/.claude/skills/c4s-brief-implementer/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: c4s-brief-implementer
+description: Implement features described in claude4spec briefs (markdown files in .claude4spec/briefs/). Briefs are self-contained — they include all context needed for implementation (entity snapshots, section diffs, narrative). After implementation, if you discover drift between the brief and reality (missing details, incorrect assumptions, edge cases not covered), generate a patch file in .claude4spec/patches/ as feedback for the specification author. Use when implementing changes in a code repository that has a .claude4spec/briefs/ directory.
+---
+
+# c4s-brief-implementer
+
+This skill describes how to implement a release brief in **your code repository**
+(not the spec repo). A brief is a self-contained markdown file under
+`.claude4spec/briefs/` that captures everything you need to ship the change:
+entity snapshots, section diffs, narrative, acceptance criteria.
+
+**This skill does NOT assume the `c4s` CLI is installed.** Briefs are designed
+to be self-contained — you do not need to read the main specification or query
+the entity database. If the brief references something you cannot find in its
+body, treat that as drift and file a patch (step 4 below).
+
+## Workflow
+
+### 1. Discover
+
+```sh
+ls .claude4spec/briefs/        # list available briefs
+cat .claude4spec/briefs/<slug>.md
+```
+
+If `.claude4spec/` is not in your current directory, walk up the directory tree
+until you find it (similar to how git finds `.git/`).
+
+### 2. Read the brief as self-contained input
+
+Every brief has YAML frontmatter:
+
+```yaml
+---
+type: brief
+from_release: v0.1.16
+to_release: v0.1.17
+generator_version: brief-author@0.1
+archived: false
+---
+```
+
+The body contains everything you need — entity snapshots, section diffs, the
+narrative of what changes, and acceptance criteria. **Do not read the main
+specification.** If the brief omits something, that is drift (see step 4).
+
+### 3. Implement
+
+Standard code flow in your target repository: read existing code, plan, edit,
+test. Stay focused on what the brief specifies.
+
+### 4. Feedback loop (patches)
+
+When you discover that the brief diverges from reality — a missing detail, an
+incorrect assumption, an edge case not covered, or anything else the
+spec-author should know — write a patch file:
+
+```sh
+mkdir -p .claude4spec/patches
+```
+
+Create `.claude4spec/patches/<brief-slug>-<short-desc>.md` with this format:
+
+```markdown
+---
+type: patch
+brief: v0-1-16-to-v0-1-17.md      # path relative to briefs/
+patch_kind: drift                  # drift | missing | incorrect | clarification
+created_at: 2026-05-11T17:32:00Z
+created_by: claude-code            # or "cursor", "aider", ...
+---
+
+# Patch — short title
+
+## What I found
+
+…description of the drift / missing detail / incorrect assumption…
+
+## Suggestion
+
+…what the spec-author should consider in a follow-up brief or entity edits…
+```
+
+Patch-kind values:
+
+- `drift` — the brief described behavior X, but the codebase already does Y.
+- `missing` — the brief is silent on a detail you had to decide yourself.
+- `incorrect` — the brief is factually wrong about existing code.
+- `clarification` — the brief is ambiguous; you guessed but it should be made
+  explicit for next time.
+
+The `.claude4spec/patches/` directory is created **lazily** — only when you
+file your first patch. The claude4spec server does NOT create it.
+
+### 5. Hand-off
+
+The spec-author reads patches manually (`ls .claude4spec/patches/`, `cat`)
+and folds them into the next brief or entity edits. There is no UI listing in
+this release — patches are raw markdown.
+
+## Notes
+
+This file is **fully managed** by claude4spec — it is overwritten on every
+server start when its rendered content changes. Do not edit it by hand.

package/.claude/skills/c4s-spec-reader/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: c4s-spec-reader
+description: Read claude4spec specification entities (endpoints, DTOs, tables, AC, UI views) referenced from markdown pages through XML tags like <inline_mention/>, <single_element/>, <tagged_list/>. Use when working in a repository whose pages/ contain these tags or whose .claude4spec/ directory exists. Resolves entity slugs to full data via c4s CLI or c4s-reader MCP server.
+---
+
+# c4s-spec-reader
+
+This repository contains a claude4spec specification. Pages (`*.md`) reference
+entities stored in `.claude4spec/db.sqlite` through XML tags. This skill teaches
+you how to resolve them.
+
+All commands below walk up from the agent's cwd to the nearest `.claude4spec/` —
+no absolute paths are required.
+
+## Resolving a tag
+
+Install `claude4spec` (Node 20+) and use the `c4s` CLI. Subcommand names match
+XML tag names 1:1.
+
+| XML tag | CLI equivalent |
+|---------|----------------|
+| `<inline_mention type="endpoint" slug="X"/>` | `c4s inline_mention --type endpoint --slug X` |
+| `<single_element type="dto" slug="X"/>` | `c4s single_element --type dto --slug X` |
+| `<element_list type="endpoint" slugs="a,b,c"/>` | `c4s element_list --type endpoint --slugs a,b,c` |
+| `<tagged_list type="dto" tags="auth" filter="and"/>` | `c4s tagged_list --type dto --tags auth --filter and` |
+| `<tagged_list_mixed tags="public"/>` | `c4s tagged_list_mixed --tags public` |
+
+## Expanding a whole page
+
+```sh
+c4s resolve some-page.md              # writes markdown with tags expanded inline
+c4s resolve some-page.md --format json   # writes { content, resolved: [...] }
+```
+
+## Discovery
+
+- `c4s catalog` — entity types, versions, and JSON Schema per view.
+- `c4s list-tags` — all tags with per-type counts.
+- `c4s list-slugs --type endpoint` — all slugs for a given type.
+
+All output is JSON (pretty) by default. Use `--compact` for pipelines and
+`--format text` for terminal-friendly output. Errors go to stderr as JSON with
+an exit code > 0.
+
+The database is opened **read-only** — `c4s` never mutates the project.
+

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-05-13
+
+Initial public release.
+
+### Added
+- `claude4spec` CLI — local-first editor for system specifications (markdown + SQLite).
+- `c4s` CLI — read specification entities (endpoints, DTOs, tables, AC, UI views) by slug.
+- `c4s-mcp` — MCP server for reading specification entities.
+- React-based web editor with tiptap, chat overlay, and live page rendering.
+- Skills `c4s-spec-reader` and `c4s-brief-implementer` for Claude Code integration.
+- Acceptance Criteria entity and tooling.
+- Briefs and patches workflow for spec-driven implementation.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Tomala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# claude4spec
+
+Local-first spec editor — markdown + SQLite + AI agent.
+
+`claude4spec` is a developer tool for writing and maintaining **system specifications** alongside your code. It runs entirely on your machine: a web-based editor (tiptap + React), a local SQLite database for structured entities (endpoints, DTOs, tables, acceptance criteria, UI views), and a built-in AI chat for spec authoring assistance.
+
+## Why
+
+- **Specifications live with the code.** No external SaaS, no copy-paste between Notion and your repo.
+- **Structured entities, not just markdown.** Endpoints, DTOs, and AC are first-class records you can reference, link, and query.
+- **Briefs → implementation.** Specs can produce self-contained implementation briefs that an AI coding agent (Claude Code) can execute directly.
+- **Open data.** Everything is markdown files + a SQLite file in your repo. No vendor lock-in.
+
+## Install & run
+
+```bash
+npx @inharness-ai/claude4spec
+```
+
+This launches the editor on `http://localhost:3000` and creates a `.claude4spec/` directory in the current working directory (database + config).
+
+For a global install:
+
+```bash
+npm i -g @inharness-ai/claude4spec
+claude4spec
+```
+
+## CLIs
+
+| Command       | Purpose                                                                 |
+|---------------|-------------------------------------------------------------------------|
+| `claude4spec` | Launch the web editor.                                                  |
+| `c4s`         | Read specification entities from the terminal (`c4s endpoint <slug>`).  |
+| `c4s-mcp`     | MCP server exposing specification entities to MCP-aware clients.        |
+
+## Claude Code integration
+
+When used inside a Claude Code project, this package installs two skills:
+
+- **`c4s-spec-reader`** — resolves XML entity tags (`<inline_mention/>`, `<single_element/>`, `<tagged_list/>`) in markdown pages into full entity data.
+- **`c4s-brief-implementer`** — implements features described in self-contained briefs from `.claude4spec/briefs/`.
+
+## Requirements
+
+- Node.js >= 20
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/bin/agent-md-template.d.ts

@@ -0,0 +1 @@
+export declare const AGENT_MD_TEMPLATE = "# Integration guide for external AI agents\n\nThis directory contains a claude4spec specification. Pages (`*.md`) reference\nentities stored in `.claude4spec/db.sqlite` through XML tags.\n\n## Resolving a tag\n\nInstall `claude4spec` (Node 20+) and use the `c4s` CLI. Subcommand names\nmatch XML tag names 1:1.\n\n| XML tag | CLI equivalent |\n|---------|----------------|\n| `<inline_mention type=\"endpoint\" slug=\"X\"/>` | `c4s inline_mention --type endpoint --slug X` |\n| `<single_element type=\"dto\" slug=\"X\"/>` | `c4s single_element --type dto --slug X` |\n| `<element_list type=\"endpoint\" slugs=\"a,b,c\"/>` | `c4s element_list --type endpoint --slugs a,b,c` |\n| `<tagged_list type=\"dto\" tags=\"auth\" filter=\"and\"/>` | `c4s tagged_list --type dto --tags auth --filter and` |\n| `<tagged_list_mixed tags=\"public\"/>` | `c4s tagged_list_mixed --tags public` |\n\n## Expanding a whole page\n\n```sh\nc4s resolve some-page.md              # writes markdown with tags expanded inline\nc4s resolve some-page.md --format json   # writes { content, resolved: [...] }\n```\n\n## Discovery\n\n- `c4s catalog` \u2014 entity types, versions, and JSON Schema per view.\n- `c4s list-tags` \u2014 all tags with per-type counts.\n- `c4s list-slugs --type endpoint` \u2014 all slugs for a given type.\n\nAll output is JSON (pretty) by default. Use `--compact` for pipelines and\n`--format text` for terminal-friendly output. Errors go to stderr as JSON with\nan exit code > 0.\n\nThe database is opened **read-only** \u2014 `c4s` never mutates the project.\n\n## MCP server (for MCP-aware agents)\n\nAgents that prefer typed MCP tools over shell-out (Claude Code, Cursor,\nWindsurf, ...) can register `c4s-reader` as an MCP server. Add to your\neditor's MCP config (`.mcp.json` for Claude Code, `~/.cursor/mcp.json` for\nCursor, ...):\n\n```json\n{\n  \"mcpServers\": {\n    \"c4s-reader\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"claude4spec\", \"c4s-mcp\", \"--project\", \"/path/to/this/project\"]\n    }\n  }\n}\n```\n\nOr, with a global install (`npm i -g claude4spec`):\n\n```json\n{\n  \"mcpServers\": {\n    \"c4s-reader\": {\n      \"command\": \"c4s-mcp\",\n      \"args\": [\"--project\", \"/path/to/this/project\"]\n    }\n  }\n}\n```\n\nThe server exposes 8 readonly tools: `get_entity`, `get_entities`,\n`find_by_tag`, `get_section`, `resolve_page`, `catalog`, `list_tags`,\n`list_slugs`. Each tool that returns serialized entities accepts a `view`\nparameter (`inline_mention`, `single_element`, `element_list_item`,\n`tagged_list_item`, `detail`). Like the CLI, the database is opened\n**read-only** \u2014 writes always go through the main `claude4spec` server.\n";

package/dist/bin/agent-md-template.js

@@ -0,0 +1,76 @@
+export const AGENT_MD_TEMPLATE = `# Integration guide for external AI agents
+
+This directory contains a claude4spec specification. Pages (\`*.md\`) reference
+entities stored in \`.claude4spec/db.sqlite\` through XML tags.
+
+## Resolving a tag
+
+Install \`claude4spec\` (Node 20+) and use the \`c4s\` CLI. Subcommand names
+match XML tag names 1:1.
+
+| XML tag | CLI equivalent |
+|---------|----------------|
+| \`<inline_mention type="endpoint" slug="X"/>\` | \`c4s inline_mention --type endpoint --slug X\` |
+| \`<single_element type="dto" slug="X"/>\` | \`c4s single_element --type dto --slug X\` |
+| \`<element_list type="endpoint" slugs="a,b,c"/>\` | \`c4s element_list --type endpoint --slugs a,b,c\` |
+| \`<tagged_list type="dto" tags="auth" filter="and"/>\` | \`c4s tagged_list --type dto --tags auth --filter and\` |
+| \`<tagged_list_mixed tags="public"/>\` | \`c4s tagged_list_mixed --tags public\` |
+
+## Expanding a whole page
+
+\`\`\`sh
+c4s resolve some-page.md              # writes markdown with tags expanded inline
+c4s resolve some-page.md --format json   # writes { content, resolved: [...] }
+\`\`\`
+
+## Discovery
+
+- \`c4s catalog\` — entity types, versions, and JSON Schema per view.
+- \`c4s list-tags\` — all tags with per-type counts.
+- \`c4s list-slugs --type endpoint\` — all slugs for a given type.
+
+All output is JSON (pretty) by default. Use \`--compact\` for pipelines and
+\`--format text\` for terminal-friendly output. Errors go to stderr as JSON with
+an exit code > 0.
+
+The database is opened **read-only** — \`c4s\` never mutates the project.
+
+## MCP server (for MCP-aware agents)
+
+Agents that prefer typed MCP tools over shell-out (Claude Code, Cursor,
+Windsurf, ...) can register \`c4s-reader\` as an MCP server. Add to your
+editor's MCP config (\`.mcp.json\` for Claude Code, \`~/.cursor/mcp.json\` for
+Cursor, ...):
+
+\`\`\`json
+{
+  "mcpServers": {
+    "c4s-reader": {
+      "command": "npx",
+      "args": ["-y", "claude4spec", "c4s-mcp", "--project", "/path/to/this/project"]
+    }
+  }
+}
+\`\`\`
+
+Or, with a global install (\`npm i -g claude4spec\`):
+
+\`\`\`json
+{
+  "mcpServers": {
+    "c4s-reader": {
+      "command": "c4s-mcp",
+      "args": ["--project", "/path/to/this/project"]
+    }
+  }
+}
+\`\`\`
+
+The server exposes 8 readonly tools: \`get_entity\`, \`get_entities\`,
+\`find_by_tag\`, \`get_section\`, \`resolve_page\`, \`catalog\`, \`list_tags\`,
+\`list_slugs\`. Each tool that returns serialized entities accepts a \`view\`
+parameter (\`inline_mention\`, \`single_element\`, \`element_list_item\`,
+\`tagged_list_item\`, \`detail\`). Like the CLI, the database is opened
+**read-only** — writes always go through the main \`claude4spec\` server.
+`;
+//# sourceMappingURL=agent-md-template.js.map

package/dist/bin/agent-md-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-md-template.js","sourceRoot":"","sources":["../../src/bin/agent-md-template.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0EhC,CAAC"}

package/dist/bin/bootstrap-template.d.ts

@@ -0,0 +1 @@
+export declare const BOOTSTRAP_TEMPLATE = "# Welcome to claude4spec\n\nThis is your first page. Start writing your specification here.\n\n## Quick start\n\n- Press `/` to invoke slash commands (`/endpoint`, `/dto`, `/dbtable`, `/dep`, `/todo`, ...).\n- Open the chat on the right edge and ask the agent to scaffold entities for you.\n- Alt+click (option+click on macOS) any chip to edit its attributes.\n- Delete this page once you have your own entries.\n";

package/dist/bin/bootstrap-template.js

@@ -0,0 +1,12 @@
+export const BOOTSTRAP_TEMPLATE = `# Welcome to claude4spec
+
+This is your first page. Start writing your specification here.
+
+## Quick start
+
+- Press \`/\` to invoke slash commands (\`/endpoint\`, \`/dto\`, \`/dbtable\`, \`/dep\`, \`/todo\`, ...).
+- Open the chat on the right edge and ask the agent to scaffold entities for you.
+- Alt+click (option+click on macOS) any chip to edit its attributes.
+- Delete this page once you have your own entries.
+`;
+//# sourceMappingURL=bootstrap-template.js.map

package/dist/bin/bootstrap-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap-template.js","sourceRoot":"","sources":["../../src/bin/bootstrap-template.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,kBAAkB,GAAG;;;;;;;;;;CAUjC,CAAC"}

package/dist/bin/c4s/args.d.ts

@@ -0,0 +1,13 @@
+export interface ParsedArgs {
+    command: string | null;
+    positional: string[];
+    flags: Map<string, string | boolean>;
+    project?: string;
+    format: 'json' | 'text';
+    compact: boolean;
+    sortKeys: boolean;
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function requireString(args: ParsedArgs, flag: string): string;
+export declare function optionalString(args: ParsedArgs, flag: string): string | undefined;
+export declare function requireStringList(args: ParsedArgs, flag: string): string[];

package/dist/bin/c4s/args.js

@@ -0,0 +1,82 @@
+import { CliError } from './errors.js';
+const KNOWN_BOOLEAN_FLAGS = new Set(['compact', 'sort-keys', 'help', 'version']);
+export function parseArgs(argv) {
+    const result = {
+        command: null,
+        positional: [],
+        flags: new Map(),
+        format: 'json',
+        compact: false,
+        sortKeys: false,
+    };
+    let i = 0;
+    if (argv[0] && !argv[0].startsWith('-')) {
+        result.command = argv[0];
+        i = 1;
+    }
+    for (; i < argv.length; i++) {
+        const token = argv[i];
+        if (!token)
+            continue;
+        if (!token.startsWith('--')) {
+            result.positional.push(token);
+            continue;
+        }
+        const eqIdx = token.indexOf('=');
+        const name = eqIdx >= 0 ? token.slice(2, eqIdx) : token.slice(2);
+        let value;
+        if (eqIdx >= 0) {
+            value = token.slice(eqIdx + 1);
+        }
+        else if (KNOWN_BOOLEAN_FLAGS.has(name)) {
+            value = true;
+        }
+        else {
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith('--')) {
+                value = true;
+            }
+            else {
+                value = next;
+                i++;
+            }
+        }
+        result.flags.set(name, value);
+    }
+    const format = result.flags.get('format');
+    if (typeof format === 'string') {
+        if (format !== 'json' && format !== 'text') {
+            throw new CliError('INVALID_ARGS', `--format must be 'json' or 'text', got '${format}'`);
+        }
+        result.format = format;
+    }
+    if (result.flags.get('compact') === true)
+        result.compact = true;
+    if (result.flags.get('sort-keys') === true)
+        result.sortKeys = true;
+    const project = result.flags.get('project');
+    if (typeof project === 'string')
+        result.project = project;
+    return result;
+}
+export function requireString(args, flag) {
+    const v = args.flags.get(flag);
+    if (typeof v !== 'string' || !v) {
+        throw new CliError('INVALID_ARGS', `--${flag} is required`);
+    }
+    return v;
+}
+export function optionalString(args, flag) {
+    const v = args.flags.get(flag);
+    if (typeof v === 'string' && v)
+        return v;
+    return undefined;
+}
+export function requireStringList(args, flag) {
+    const raw = requireString(args, flag);
+    return raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+//# sourceMappingURL=args.js.map

package/dist/bin/c4s/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../../src/bin/c4s/args.ts"],"names":[],"mappings":"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"}

package/dist/bin/c4s/commands/_meta.d.ts

@@ -0,0 +1,2 @@
+import type { SerializeResult } from '../../../server/serialization/types.js';
+export declare function withMeta(result: SerializeResult): unknown;

package/dist/bin/c4s/commands/_meta.js

@@ -0,0 +1,13 @@
+export function withMeta(result) {
+    if (!result.fallback && !result.error)
+        return result.data;
+    if (typeof result.data === 'object' && result.data !== null) {
+        return {
+            ...result.data,
+            ...(result.fallback ? { _fallback: true } : {}),
+            ...(result.error ? { _error: result.error } : {}),
+        };
+    }
+    return result.data;
+}
+//# sourceMappingURL=_meta.js.map

package/dist/bin/c4s/commands/_meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_meta.js","sourceRoot":"","sources":["../../../../src/bin/c4s/commands/_meta.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,QAAQ,CAAC,MAAuB;IAC9C,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC;IAC1D,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QAC5D,OAAO;YACL,GAAI,MAAM,CAAC,IAAe;YAC1B,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/C,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAClD,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC"}

package/dist/bin/c4s/commands/catalog.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedArgs } from '../args.js';
+export declare function runCatalog(args: ParsedArgs): void;

package/dist/bin/c4s/commands/catalog.js

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createContext } from '../context.js';
+import { writeOutput } from '../output.js';
+export function runCatalog(args) {
+    const ctx = createContext(args);
+    try {
+        const catalog = ctx.registry.catalog(ctx.reader, ctx.db);
+        writeOutput({ ...catalog, claude4spec: readPackageVersion() }, args);
+    }
+    finally {
+        ctx.close();
+    }
+}
+function readPackageVersion() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        // dist/bin/c4s/commands → packageRoot, or src/bin/c4s/commands → packageRoot
+        const roots = [
+            path.resolve(here, '..', '..', '..', '..'),
+            path.resolve(here, '..', '..', '..'),
+        ];
+        for (const root of roots) {
+            const pkgPath = path.join(root, 'package.json');
+            if (fs.existsSync(pkgPath)) {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+                if (pkg.version)
+                    return pkg.version;
+            }
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return 'unknown';
+}
+//# sourceMappingURL=catalog.js.map

package/dist/bin/c4s/commands/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../../../src/bin/c4s/commands/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,MAAM,UAAU,UAAU,CAAC,IAAgB;IACzC,MAAM,GAAG,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QACzD,WAAW,CAAC,EAAE,GAAG,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;IACvE,CAAC;YAAS,CAAC;QACT,GAAG,CAAC,KAAK,EAAE,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,kBAAkB;IACzB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1D,6EAA6E;QAC7E,MAAM,KAAK,GAAG;YACZ,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC;YAC1C,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC;SACrC,CAAC;QACF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;YAChD,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAyB,CAAC;gBACjF,IAAI,GAAG,CAAC,OAAO;oBAAE,OAAO,GAAG,CAAC,OAAO,CAAC;YACtC,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,YAAY;IACd,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/bin/c4s/commands/detail.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedArgs } from '../args.js';
+export declare function runDetail(args: ParsedArgs): void;

package/dist/bin/c4s/commands/detail.js

@@ -0,0 +1,22 @@
+import { requireString } from '../args.js';
+import { createContext } from '../context.js';
+import { CliError } from '../errors.js';
+import { writeOutput } from '../output.js';
+import { normalizeEntityType } from '../type-validation.js';
+import { withMeta } from './_meta.js';
+export function runDetail(args) {
+    const type = normalizeEntityType(requireString(args, 'type'));
+    const slug = requireString(args, 'slug');
+    const ctx = createContext(args);
+    try {
+        const entity = ctx.reader.getEntity(type, slug);
+        if (!entity)
+            throw new CliError('ENTITY_NOT_FOUND', `${type}/${slug}`);
+        const result = ctx.registry.serializeEntity(type, 'detail', entity, ctx.reader);
+        writeOutput(withMeta(result), args);
+    }
+    finally {
+        ctx.close();
+    }
+}
+//# sourceMappingURL=detail.js.map

package/dist/bin/c4s/commands/detail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detail.js","sourceRoot":"","sources":["../../../../src/bin/c4s/commands/detail.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,MAAM,UAAU,SAAS,CAAC,IAAgB;IACxC,MAAM,IAAI,GAAG,mBAAmB,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9D,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAChD,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,QAAQ,CAAC,kBAAkB,EAAE,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC;QACvE,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QAChF,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;YAAS,CAAC;QACT,GAAG,CAAC,KAAK,EAAE,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/bin/c4s/commands/element-list.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedArgs } from '../args.js';
+export declare function runElementList(args: ParsedArgs): void;

package/dist/bin/c4s/commands/element-list.js

@@ -0,0 +1,23 @@
+import { requireString, requireStringList } from '../args.js';
+import { createContext } from '../context.js';
+import { CliError } from '../errors.js';
+import { writeOutput } from '../output.js';
+import { normalizeEntityType } from '../type-validation.js';
+import { withMeta } from './_meta.js';
+export function runElementList(args) {
+    const type = normalizeEntityType(requireString(args, 'type'));
+    const slugs = requireStringList(args, 'slugs');
+    const ctx = createContext(args);
+    try {
+        const { items: entities, missing } = ctx.reader.getEntities(type, slugs);
+        if (entities.length === 0) {
+            throw new CliError('ENTITY_NOT_FOUND', `no ${type} found for slugs: ${slugs.join(', ')}`);
+        }
+        const items = entities.map((entity) => withMeta(ctx.registry.serializeEntity(type, 'element_list_item', entity, ctx.reader)));
+        writeOutput({ items, missing }, args);
+    }
+    finally {
+        ctx.close();
+    }
+}
+//# sourceMappingURL=element-list.js.map

package/dist/bin/c4s/commands/element-list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-list.js","sourceRoot":"","sources":["../../../../src/bin/c4s/commands/element-list.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,MAAM,UAAU,cAAc,CAAC,IAAgB;IAC7C,MAAM,IAAI,GAAG,mBAAmB,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9D,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC/C,MAAM,GAAG,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC;QACH,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACzE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,QAAQ,CAChB,kBAAkB,EAClB,MAAM,IAAI,qBAAqB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAClD,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CACpC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CACtF,CAAC;QACF,WAAW,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI,CAAC,CAAC;IACxC,CAAC;YAAS,CAAC;QACT,GAAG,CAAC,KAAK,EAAE,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/bin/c4s/commands/inline-mention.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedArgs } from '../args.js';
+export declare function runInlineMention(args: ParsedArgs): void;

package/dist/bin/c4s/commands/inline-mention.js

@@ -0,0 +1,22 @@
+import { requireString } from '../args.js';
+import { createContext } from '../context.js';
+import { CliError } from '../errors.js';
+import { writeOutput } from '../output.js';
+import { normalizeEntityType } from '../type-validation.js';
+import { withMeta } from './_meta.js';
+export function runInlineMention(args) {
+    const type = normalizeEntityType(requireString(args, 'type'));
+    const slug = requireString(args, 'slug');
+    const ctx = createContext(args);
+    try {
+        const entity = ctx.reader.getEntity(type, slug);
+        if (!entity)
+            throw new CliError('ENTITY_NOT_FOUND', `${type}/${slug}`);
+        const result = ctx.registry.serializeEntity(type, 'inline_mention', entity, ctx.reader);
+        writeOutput(withMeta(result), args);
+    }
+    finally {
+        ctx.close();
+    }
+}
+//# sourceMappingURL=inline-mention.js.map

package/dist/bin/c4s/commands/inline-mention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline-mention.js","sourceRoot":"","sources":["../../../../src/bin/c4s/commands/inline-mention.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,MAAM,UAAU,gBAAgB,CAAC,IAAgB;IAC/C,MAAM,IAAI,GAAG,mBAAmB,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9D,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAChD,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,QAAQ,CAAC,kBAAkB,EAAE,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC;QACvE,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QACxF,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;YAAS,CAAC;QACT,GAAG,CAAC,KAAK,EAAE,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/bin/c4s/commands/list-slugs.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedArgs } from '../args.js';
+export declare function runListSlugs(args: ParsedArgs): void;