@specpin/cli 0.0.1 → 0.0.2

package/README.md

@@ -34,6 +34,21 @@ specpin validate  # lint the spec corpus (CI-friendly)
 specpin --help
 ```
 
+## Author specs with a coding agent
+
+This package bundles a portable skill that teaches a coding agent (Claude Code,
+Cursor, etc.) to author schema-valid specs and drive the CLI. The CLI adds no
+LLM; the host agent is the author. It ships in the tarball and is reachable
+without installing:
+
+```
+https://unpkg.com/@specpin/cli@latest/skill/SKILL.md
+```
+
+Point your agent at that URL (or the installed `skill/SKILL.md`), then it writes
+`.specs/` and runs `specpin validate`. See
+[`docs/ai-authoring.md`](https://github.com/lamngockhuong/specpin/blob/main/docs/ai-authoring.md).
+
 ## How it works
 
 - The npm package version matches the CLI release version. Postinstall fetches

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specpin/cli",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Specpin sidecar CLI: init + serve the .specs/ knowledge layer for the Specpin browser extension. Installs the matching prebuilt Go binary.",
   "keywords": [
     "specpin",
@@ -25,11 +25,15 @@
     "node": ">=20"
   },
   "scripts": {
-    "postinstall": "node scripts/postinstall.mjs"
+    "postinstall": "node scripts/postinstall.mjs",
+    "sync-skill": "node scripts/sync-skill.mjs",
+    "check-skill": "node scripts/sync-skill.mjs --check",
+    "prepack": "node scripts/sync-skill.mjs"
   },
   "files": [
     "bin",
     "scripts",
+    "skill",
     "README.md"
   ],
   "publishConfig": {

package/scripts/sync-skill.mjs

@@ -0,0 +1,80 @@
+// Sync the canonical skill (apps/cli/skill/) into the npm package
+// (apps/cli/npm/skill/) so it ships in the published tarball and is reachable
+// via unpkg/jsdelivr. This mirrors how `make sync-schema` copies the SSOT
+// schema into the Go embed location: one source of truth, a checked-in copy,
+// and a drift gate.
+//
+//   node scripts/sync-skill.mjs          copy source -> bundled (default)
+//   node scripts/sync-skill.mjs --check  exit non-zero if they differ (CI gate)
+//
+// npm tarballs do not reliably follow symlinks across environments, so the
+// bundled copy is a real checked-in directory kept honest by --check.
+
+import { readdir, readFile, cp, rm } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const SRC = join(here, "..", "..", "skill"); // apps/cli/skill
+const DST = join(here, "..", "skill"); // apps/cli/npm/skill
+
+// Recursively list files (relative paths) under a directory. Returns [] if the
+// directory is absent rather than throwing, so --check can report a clean miss.
+async function listFiles(root) {
+  const out = [];
+  async function walk(dir) {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch (err) {
+      if (err.code === "ENOENT") return;
+      throw err;
+    }
+    for (const e of entries) {
+      const abs = join(dir, e.name);
+      if (e.isDirectory()) await walk(abs);
+      else out.push(relative(root, abs));
+    }
+  }
+  await walk(root);
+  return out.sort();
+}
+
+async function copy() {
+  const files = await listFiles(SRC);
+  if (files.length === 0) {
+    console.error(`sync-skill: no files under ${SRC}; nothing to sync`);
+    process.exit(1);
+  }
+  // Clear the destination so deletions in source propagate, then copy fresh.
+  await rm(DST, { recursive: true, force: true });
+  await cp(SRC, DST, { recursive: true });
+  console.log(`sync-skill: copied ${files.length} file(s) -> ${relative(process.cwd(), DST)}`);
+}
+
+async function check() {
+  const [srcFiles, dstFiles] = await Promise.all([listFiles(SRC), listFiles(DST)]);
+  const offending = [];
+
+  const srcSet = new Set(srcFiles);
+  const dstSet = new Set(dstFiles);
+  for (const rel of srcFiles) if (!dstSet.has(rel)) offending.push(`missing in bundle: ${rel}`);
+  for (const rel of dstFiles) if (!srcSet.has(rel)) offending.push(`stale in bundle: ${rel}`);
+
+  for (const rel of srcFiles) {
+    if (!dstSet.has(rel)) continue;
+    const [a, b] = await Promise.all([readFile(join(SRC, rel)), readFile(join(DST, rel))]);
+    if (!a.equals(b)) offending.push(`content differs: ${rel}`);
+  }
+
+  if (offending.length > 0) {
+    console.error("sync-skill: bundled skill drifted from apps/cli/skill/:");
+    for (const o of offending) console.error(`  ${o}`);
+    console.error("Run `npm run sync-skill` in apps/cli/npm to re-sync.");
+    process.exit(1);
+  }
+  console.log("sync-skill: bundled skill in sync");
+}
+
+if (process.argv.includes("--check")) await check();
+else await copy();

package/skill/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: specpin
+description: >-
+  Author and pin living business specs (rules, descriptions, acceptance
+  criteria) onto the elements of a running web UI, and drive the specpin
+  sidecar CLI. Use when the user wants to document UI elements with versioned
+  specs, write or edit .specs/*.spec.json files, run "specpin serve"/"specpin
+  validate", or mentions specpin, spec.json, or pinning specs to a page. The
+  host coding agent is the author: it reads the UI source, writes schema-valid
+  JSON, registers it in the manifest, and validates. No application code is
+  generated.
+---
+
+# Specpin: author business specs for a running web UI
+
+Specpin is a Git-native knowledge layer. It pins business specifications onto
+the elements of a web UI you already have, then renders them in the browser as
+you hover or browse. It is NOT a code generator and does not write application
+code. You (the coding agent) author JSON spec files in the consumer repo's
+`.specs/` directory; the `specpin` CLI serves and validates them; a browser
+extension matches each spec's element fingerprint against the live DOM and
+renders it.
+
+Flow: `.specs/` (in the repo) -> `specpin serve` (Go sidecar, localhost) ->
+browser extension (match + render).
+
+Your job: read the UI source, write `<area>.spec.json` files that conform to
+schema v1, register them in `manifest.json`, and confirm `specpin validate`
+exits 0.
+
+## Setup
+
+No login, no API key, no model. The sidecar is localhost-only and prints its own
+bearer token on `serve`. Contrast with agent CLIs that need auth: there is
+nothing to authenticate here.
+
+1. Check the CLI: `specpin --version` (or `npx @specpin/cli --version`).
+2. If absent, install: `npm i -g @specpin/cli` (or use `npx @specpin/cli ...`).
+3. Work inside the consumer repo. Author into its `.specs/` directory, never a
+   temp directory.
+
+## Authoring workflow (the core loop)
+
+a. **Scaffold** (only if `.specs/manifest.json` is absent):
+   `specpin init --project "<Name>" --domains <origin>` where `<origin>` is
+   where the UI runs, e.g. `localhost:3000`. This refuses to overwrite an
+   existing manifest.
+
+b. **Identify the target element** in the UI source (JSX/HTML/Vue/Svelte) and
+   decide the fingerprint approach. Specpin is non-intrusive by default: build the
+   fingerprint from signals the element **already has** (an existing
+   `data-testid` / `data-spec-id`, a non-generated `id`, an `aria-label`, or a
+   unique selector) and do NOT edit the app's source. Adding a `data-spec-id` is
+   an optional opt-in upgrade for the most resilient anchor, only when the project
+   agrees to small markup additions. See `references/fingerprint-strategy.md`.
+
+c. **Write `<area>.spec.json`** (one file per page or feature). It has a `group`
+   string and a `specs[]` array. Each spec needs:
+   - `id`: stable, unique within the project, e.g. `"login-submit-btn"`.
+   - `title`, `description`: **locale-keyed objects**, never flat strings,
+     e.g. `{ "en": "Log in button" }`. `description` must be non-empty.
+   - `businessRules` (optional): array of locale-keyed objects, one rule each.
+   - `tags` (optional): plain string array (not localized).
+   - `preferredDisplayMode` (optional): `tooltip` | `sidebar` | `modal`
+     (`overlay` and `inline-badge` are reserved and fall back to `tooltip`).
+   - `fingerprint`: the element link (required). See the fingerprint reference.
+   - `meta`: set `"source": "ai-generated"` for specs you author, plus
+     `createdBy`, `createdAt`, `updatedAt` (RFC3339).
+
+   `description` and each `businessRules` item may use a small, safe Markdown
+   subset (bold, italic, `[label](url)` links, and lists in `description`).
+   See `references/schema-authoring.md`.
+
+d. **Register the file** in `manifest.json` under `specFiles[]`. A spec file on
+   disk that is not listed (or listed but missing) trips a drift warning.
+
+e. **Validate**: `specpin validate` (or `specpin validate --dir <path>`).
+   Exit 0 = done. Exit 1 = fix the reported `FAIL` lines and re-run. Exit 2 =
+   the check could not run (no manifest, wrong `--dir`).
+
+f. **Preview** (optional): `specpin serve` prints a URL + token to paste into the
+   extension, then specs render live on their elements with SSE live-reload.
+
+## Do / Don't
+
+DO:
+- Set `meta.source: "ai-generated"` on every spec you author (output is meant to
+  be reviewed by a human).
+- Keep one `<area>.spec.json` per page or feature; name it after the area.
+- Prefer an anchor the element **already has** (an existing `data-testid` /
+  `data-spec-id`, a non-generated `id`, or an `aria-label`): it gives exact
+  matching with zero source changes.
+- Ground every business rule in real code or stated requirements.
+
+DON'T:
+- Edit the app's source to add `data-spec-id` / `data-testid` unless the project
+  opts in. Specpin attaches to the UI you already have; adding an anchor is an
+  optional resilience upgrade, never a requirement. Default to synthesizing the
+  fingerprint from the existing markup.
+- Invent business rules not supported by the code or the user's requirements.
+- Use flat strings for `title` / `description` / `businessRules`: both
+  validators reject `"title": "Log in"`. Use `{ "en": "Log in" }`.
+- Add keys not in the schema: objects are `additionalProperties: false`.
+- Hand-edit generated artifacts or write files outside `.specs/`.
+
+## Reading `specpin validate` output
+
+Each file prints `OK <file>` or `FAIL <file>` followed by indented error lines,
+then a summary `N files checked, M error(s)`. Drift between `manifest.specFiles`
+and on-disk files prints `warning:` lines (or `FAIL:` under `--strict-manifest`).
+
+- Exit 0: all valid. You are done.
+- Exit 1: schema violations or an unreadable spec file. Read each `FAIL` block,
+  fix the JSON, re-run.
+- Exit 2: could not run (missing `.specs/`, no `manifest.json`, or `--dir`
+  pointed at the repo root instead of `.specs/`). Fix the path or run `init`.
+
+## Staying up to date
+
+This skill ships inside `@specpin/cli` and is version-synced with the CLI. To
+fetch the latest copy without installing:
+
+- `https://unpkg.com/@specpin/cli@latest/skill/SKILL.md`
+- `https://unpkg.com/@specpin/cli@latest/skill/references/<file>.md`
+- Schema for `$schema` autocomplete: `https://specpin.ohnice.app/schema/v1.json`
+  (also `https://unpkg.com/@specpin/spec-schema/schema/v1.json`).
+
+Compare `npm view @specpin/cli version` against your installed
+`specpin --version`; refresh the skill if they differ.
+
+## References (load on demand)
+
+- `references/schema-authoring.md`: the full v1 shape (Manifest, SpecFile, Spec,
+  LocalizedString, fingerprint, meta), a complete minimal valid example, and the
+  Markdown subset.
+- `references/fingerprint-strategy.md`: the test-id-first decision tree and how
+  to derive each fingerprint field from source.
+- `references/cli-commands.md`: every command, its flags, and exit-code
+  semantics.

package/skill/references/cli-commands.md

@@ -0,0 +1,73 @@
+# CLI commands
+
+Run `specpin <command>` (or `npx @specpin/cli <command>`). No auth or keys.
+
+## init
+
+Scaffold `.specs/manifest.json` in the current directory.
+
+```bash
+specpin init --project "Acme CRM" --domains localhost:3000
+```
+
+- `--project` (required): manifest `project` name.
+- `--domains` (optional): comma-separated origins, e.g. `localhost:3000,app.acme.io`.
+- Writes a manifest with `$schema`, `version: "1.0"`, empty `specFiles`, and
+  default `settings` (`defaultLocale: en`, `matchConfidenceThreshold: 0.6`,
+  `defaultDisplayMode: tooltip`).
+- Refuses to overwrite an existing `.specs/manifest.json` (exits with an error).
+
+## serve
+
+Serve `.specs/` over a hardened localhost HTTP API with SSE live-reload.
+
+```bash
+specpin serve              # auto-pick a free port
+specpin serve --port 4317  # pin a port
+specpin serve --dir path/to/.specs
+```
+
+- `--port` (default 0 = auto-pick), `--dir` (default `.specs`).
+- Prints the project name, dir, URL (`http://127.0.0.1:<port>`), and a bearer
+  token. Paste URL + token into the extension Options page.
+- Binds `127.0.0.1` only; fails early if `manifest.json` is missing (usually
+  `--dir` pointed at the repo root instead of `.specs/`). Ctrl+C to stop.
+
+## validate
+
+Validate the corpus against the embedded schema, offline. CI-friendly.
+
+```bash
+specpin validate                 # checks ./.specs
+specpin validate --dir path/to/.specs
+specpin validate --strict-manifest
+```
+
+- `--dir` (default `.specs`), `--strict-manifest` (turn drift warnings into failures).
+- Output: `OK <file>` or `FAIL <file>` plus indented errors per file, then
+  `N files checked, M error(s)`. Manifest/disk drift prints `warning:` lines
+  (or `FAIL:` under `--strict-manifest`).
+- Exit codes:
+  - `0`: all valid.
+  - `1`: schema violations or an unreadable/symlinked spec file (author fixes).
+  - `2`: could not run (missing `.specs/`, no `manifest.json`, internal error).
+
+## bundle
+
+Assemble `.specs/` into a Manual-import bundle for the extension (no sidecar).
+
+```bash
+specpin bundle               # prints JSON to stdout
+specpin bundle --out out.json
+```
+
+- `--dir` (default `.specs`), `--out` (write to a file instead of stdout).
+- Emits `{ "manifest": {...}, "files": { "<name>.spec.json": {...} } }`, pretty
+  printed. Paste into the extension's Manual specs import.
+- Does NOT validate. Run `specpin validate` separately for schema checks.
+
+## generate
+
+Deferred stub. AI-assisted generation is driven by your coding agent through
+this skill, not by the CLI. `specpin generate` prints a pointer to the skill and
+does nothing else. Do not rely on it to produce specs.

package/skill/references/fingerprint-strategy.md

@@ -0,0 +1,80 @@
+# Fingerprint strategy
+
+You are not running inside the browser, so you cannot capture a live element.
+You synthesize the fingerprint from source (JSX/HTML/Vue/Svelte) or a DOM dump.
+Specpin is **non-intrusive by default**: it attaches to the UI you already have,
+so do NOT edit the app's source unless the project opts in. Prefer an anchor the
+element already carries; fall back to synthesized selectors; treat adding a new
+attribute as an optional, opt-in upgrade.
+
+## Decision tree
+
+1. **Existing anchor (best, confidence 1.0, zero source changes).** If the
+   element already has a stable `data-testid` / `data-spec-id` / `data-cy` /
+   `data-qa`, set `fingerprint.testId` to it. A non-generated `id` or an
+   `aria-label` are also exact-ish anchors: set `fingerprint.id` / `ariaLabel`.
+   This is the default and preferred path: an exact match that survives refactors
+   without touching the app.
+
+2. **Synthesize from the existing markup (no edits, lower confidence).** No ready
+   anchor: derive the required fields from the source as it is (see per-field
+   derivation below). Without an exact anchor a spec may render as `needsReview`
+   in the extension, but nothing in the app changes. This is the right default for
+   any project that does not want source modifications.
+
+3. **Add a `data-spec-id` (optional, opt-in only).** ONLY when the project agrees
+   to small non-functional markup additions, add a `data-spec-id` for the most
+   resilient anchor, then fingerprint on it (step 1). Specpin works fine without
+   this; never edit source unless asked.
+
+   ```jsx
+   // React
+   <button data-spec-id="nav-logout" type="button" onClick={logout}>Log out</button>
+   ```
+   ```html
+   <!-- HTML -->
+   <button data-spec-id="nav-logout" type="button">Log out</button>
+   ```
+   ```vue
+   <!-- Vue -->
+   <button data-spec-id="nav-logout" type="button" @click="logout">Log out</button>
+   ```
+
+   Then mirror it: `"testId": "nav-logout"`. Either way, the remaining fingerprint
+   fields are still required by the schema, so fill them as below.
+
+### Per-field derivation (reading the source)
+
+- `cssSelector`: shortest unique selector, e.g. `nav button[type=button]` or
+  `form.login input[type=email]`. Prefer classes/attributes over nth-child.
+- `xpath`: e.g. `//nav//button[@type='button']`.
+- `domPath`: ancestor-to-element tag chain, e.g. `["nav", "button"]`.
+- `tagName`: lowercase tag, e.g. `"button"`.
+- `attributes`: whitelisted only (role, type, name, placeholder, href),
+  string values, e.g. `{ "type": "button" }`.
+- `positionHint`: `{ index, siblingCount }` among siblings (0-based index).
+  Estimate from source order; both are integers >= 0.
+- `textContent` (optional, nullable): the visible text, normalized, e.g.
+  `"Log out"`; `null` for inputs.
+- `ariaLabel`, `id` (optional, nullable): set if present; exclude
+  auto-generated ids like `":r1:"` or `"css-1a2b3c"` (use `null`).
+- `nearbyLabels` (optional): visible labels near the element, e.g.
+  `["Email", "Password"]`.
+- `frameworkHint` (optional): `"react" | "vue" | "angular" | "vanilla"`.
+
+## Brittleness caveat
+
+`positionHint` and `domPath` are the most fragile signals: any reorder or
+wrapper change breaks them. The CSS selector is moderately robust. A test-id is
+the only signal that survives a refactor unchanged. So for a critical element,
+fingerprint on the most stable signal it already has (an existing test-id, a
+non-generated `id`, or a unique selector); an added `data-spec-id` is the most
+robust option only if the project allows source edits.
+
+## Match order (current)
+
+The extension matches in this order: exact anchors (test-id, confidence 1.0) ->
+unique `cssSelector` (confidence 0.7) -> otherwise `needsReview`. The
+`settings.matchConfidenceThreshold` in the manifest is reserved for the deferred
+hybrid weighted scorer; exact-anchor and unique-cssSelector are the live paths
+today.

package/skill/references/schema-authoring.md

@@ -0,0 +1,147 @@
+# Schema authoring (spec v1)
+
+Distilled from the canonical schema `v1.json`
+(`$id: https://specpin.ohnice.app/schema/v1.json`, JSON Schema draft 2020-12).
+Every object is `additionalProperties: false`: unknown keys are rejected by both
+the TS (ajv) and Go validators. Add `"$schema": "https://specpin.ohnice.app/schema/v1.json"`
+to each file for editor autocomplete.
+
+## Files in `.specs/`
+
+```
+.specs/
+  manifest.json          # index + project config (required)
+  <area>.spec.json       # a group of specs (SpecFile)
+  views.json             # optional team visibility defaults (do not author by hand)
+  guides.json            # optional onboarding tours (do not author by hand)
+```
+
+## Manifest (`manifest.json`)
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `version` | string | yes | e.g. `"1.0"` |
+| `project` | string | yes | display name |
+| `domains` | string[] | yes | origins the UI runs on, e.g. `["localhost:3000"]`; empty = any |
+| `specFiles` | string[] | yes | names of the `<area>.spec.json` files |
+| `settings.defaultLocale` | string | no | fallback locale |
+| `settings.locales` | string[] | no | BCP-47 locales authored |
+| `settings.matchConfidenceThreshold` | number 0-1 | no | reserved for the deferred hybrid scorer |
+| `settings.defaultDisplayMode` | DisplayMode | no | fallback render mode |
+
+## SpecFile (`<area>.spec.json`)
+
+| Field | Type | Required |
+|-------|------|----------|
+| `group` | string (non-empty) | yes |
+| `specs` | Spec[] | yes |
+
+## Spec
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `id` | string (non-empty) | yes | unique within the project |
+| `title` | LocalizedString | yes | locale-keyed object |
+| `description` | LocalizedString | yes | locale-keyed object, each value non-empty |
+| `businessRules` | LocalizedString[] | no | one locale-keyed object per rule |
+| `tags` | string[] | no | NOT localized |
+| `preferredDisplayMode` | DisplayMode | no | overrides `settings.defaultDisplayMode` |
+| `fingerprint` | ElementFingerprint | yes | the element link |
+| `meta` | SpecMeta | no | provenance + timestamps |
+
+## LocalizedString
+
+A locale-keyed object, NOT a flat string:
+
+```json
+{ "en": "Log in button", "vi": "Nut dang nhap" }
+```
+
+- Keys are BCP-47 codes matching `^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$` (`en`, `vi`, `en-US`).
+- At least one entry (`minProperties: 1`), at most 50; each value non-empty (`minLength: 1`).
+- Flat strings are rejected: `"title": "Log in"` is invalid. Use `{ "en": "Log in" }`.
+
+## ElementFingerprint
+
+Required: `cssSelector`, `xpath`, `domPath`, `tagName`, `attributes`, `positionHint`.
+Optional (all nullable where noted): `testId`, `ariaLabel`, `id`, `textContent`,
+`nearbyLabels`, `frameworkHint`.
+
+- `domPath`: tag chain array, e.g. `["form", "button"]`.
+- `attributes`: object of whitelisted attrs (role, type, name, placeholder, href), string values.
+- `positionHint`: `{ "index": int >= 0, "siblingCount": int >= 0 }` (both required).
+- `frameworkHint`: `"react" | "vue" | "angular" | "vanilla"`.
+
+See `fingerprint-strategy.md` for how to fill these from source.
+
+## SpecMeta
+
+All four required when `meta` is present: `createdBy` (string),
+`createdAt` + `updatedAt` (RFC3339 date-time, format-checked by both validators),
+`source` (`"ai-generated" | "manual"`). Use `"ai-generated"` for specs you author.
+
+## DisplayMode
+
+`"overlay" | "tooltip" | "sidebar" | "modal" | "inline-badge"`. Implemented:
+`tooltip`, `sidebar`, `modal`. `overlay` and `inline-badge` are reserved and
+fall back to `tooltip` at render time.
+
+## Markdown subset (rendering convention only)
+
+`description` and each `businessRules` item may carry a small Markdown subset.
+The stored value stays a plain string (no schema change), so files remain
+Git-diffable.
+
+- Inline (both fields): bold `**text**`, italic `*text*` / `_text_`, links
+  `[label](url)`. Only `http`, `https`, `mailto` URLs render; others drop to text.
+- Block (`description` only): bullet lists (`- ` / `* `), numbered lists (`1. `),
+  blank-line paragraphs, single newline = line break. A `businessRules` item is
+  inline-only (one line, one list item).
+- Not supported (rendered literally): headings, blockquotes, code, tables,
+  images, underline. `title` is never interpreted as Markdown.
+
+## Complete minimal valid example
+
+`nav.spec.json`:
+
+```json
+{
+  "$schema": "https://specpin.ohnice.app/schema/v1.json",
+  "group": "Navigation",
+  "specs": [
+    {
+      "id": "nav-logout",
+      "title": { "en": "Log out button" },
+      "description": { "en": "Ends the session and returns to the login screen." },
+      "businessRules": [
+        { "en": "Clears the auth token client-side before redirecting" }
+      ],
+      "tags": ["auth"],
+      "preferredDisplayMode": "tooltip",
+      "fingerprint": {
+        "testId": "nav-logout",
+        "ariaLabel": null,
+        "id": null,
+        "cssSelector": "nav button[type=button]",
+        "xpath": "//nav//button[@type='button']",
+        "domPath": ["nav", "button"],
+        "tagName": "button",
+        "textContent": "Log out",
+        "attributes": { "type": "button" },
+        "nearbyLabels": ["Settings"],
+        "positionHint": { "index": 5, "siblingCount": 6 },
+        "frameworkHint": "react"
+      },
+      "meta": {
+        "createdBy": "agent",
+        "createdAt": "2026-06-30T00:00:00Z",
+        "updatedAt": "2026-06-30T00:00:00Z",
+        "source": "ai-generated"
+      }
+    }
+  ]
+}
+```
+
+Then add `"nav.spec.json"` to `manifest.json` `specFiles[]` and run
+`specpin validate`.