@dittowords/spec-cli 0.0.1-alpha.14 → 0.0.1-alpha.15

package/README.md

@@ -147,21 +147,37 @@ Validates all spec files: YAML parses correctly, required keys are present, surf
 
 Prints an inventory of all component specs with their surfaces, tags, and constraints.
 
-### `ditto-spec create-rule`
+### `ditto-spec rules`
 
-Creates a new rule on the Ditto platform.
+Prints every rule on the platform, grouped by style guide and section (with each section's `sectionId` and kind). Pass `--styleguide "<name-or-id>"` to limit to one guide.
+
+### `ditto-spec create-rules`
+
+Creates a batch of rules on the Ditto platform. Takes a JSON array of rules on stdin (or via `--file <path>`):
 
 ```
-ditto-spec create-rule --name "Use active voice" --description "Lead CTAs with a verb" --tags "button,call-to-action" --examples '[{"from":"Your settings","to":"Open settings"}]'
+ditto-spec create-rules <<'EOF'
+[
+  {"name": "Use active voice", "description": "Lead CTAs with a verb", "tags": ["button", "call-to-action"], "examples": [{"from": "Your settings", "to": "Open settings"}], "section": "UI Patterns"},
+  {"term": "sign up", "disallowed": ["signup", "sign-up"], "description": "Two words as a verb", "section": "Word List"}
+]
+EOF
 ```
 
+Each rule is one of two shapes:
+
+| Shape | Fields |
+|---|---|
+| Style rule | `name` (required), `description`, `examples` (array of `{from, to}`), `tags`, `section` |
+| Terminology entry | `term` (required), `disallowed` (array of strings), `description`, `tags`, `section` |
+
+Shapes can be mixed in one batch. Each rule's optional `section` (name or ID, as shown by `ditto-spec rules`) maps it to an existing section of the style guide; the section's kind must match the rule's shape (`rules` sections for style rules, `wordlist` sections for terminology entries). Rules without a `section` go to the first section of the matching kind. One API call is made per target section.
+
 | Flag | Description |
 |---|---|
-| `--name` | Rule name (required) |
-| `--description` | What the rule enforces (required) |
+| `--file <path>` | Read the JSON array from a file instead of stdin |
 | `--styleguide` | Target style guide name or ID (optional, overrides `defaultStyleguide` config) |
-| `--tags` | Comma-separated tags to scope the rule (optional) |
-| `--examples` | JSON array of `{from, to}` pairs (optional) |
+| `--section` | Default section for rules that don't specify their own (optional; applies only to rules matching the section's kind — others fall back to the first section of theirs) |
 
 After creating rules, run `ditto-spec pull` to sync them into spec files.
 
@@ -184,7 +200,7 @@ Create `dittospec.config.json` at your repo root (or any ancestor directory):
 | `roots` | Repo-relative directories to search for `.ditto.md` files. Defaults to `["."]`. |
 | `styleguides` | Optional list of style guide names or IDs to pull. Defaults to all. |
 | `locales` | Optional list of locale codes (e.g. `["de-DE", "fr-FR"]`). Includes locale-scoped style guides matching these codes. Base (no-variant) guides are always included. |
-| `defaultStyleguide` | Optional style guide name or ID for `create-rule`. Overridable with the `--styleguide` flag. Defaults to the first guide returned by the API. |
+| `defaultStyleguide` | Optional style guide name or ID for `create-rules`. Overridable with the `--styleguide` flag. Defaults to the first guide returned by the API. |
 
 Set `DITTO_API_KEY` in your environment or in a `.env` file at the repo root.
 
@@ -196,7 +212,7 @@ When you run `ditto-spec init --agent` in a Claude Code project, the CLI writes
 |---|---|
 | `/spec-component <Name>` | Analyze a component's text surfaces, scaffold a `.ditto.md` spec (or update an existing one), and sync rules from the platform. Handles child components too. |
 | `/spec-audit [Name]` | Audit copy in component instances against spec rules. Reports violations with file locations and suggested corrections. Omit the name to audit all specced components. |
-| `/spec-gaps [Name]` | Find copy patterns that should be rules but aren't. Proposes new style rules and terminology entries, then creates approved ones on the platform via `create-rule`. |
+| `/spec-gaps [Name]` | Find copy patterns that should be rules but aren't. Proposes new style rules and terminology entries, then creates approved ones on the platform via `create-rules`. |
 
 Skills are written into your repo and committed alongside your specs and config. Every team member gets them automatically — no separate plugin install.
 

package/dist/api.d.ts

@@ -20,6 +20,7 @@ export interface WordlistEntry {
     tags: string[];
 }
 export interface StyleguideSection {
+    sectionId?: string;
     name: string;
     kind: "rules" | "wordlist";
     rules: StyleRule[] | WordlistEntry[];
@@ -54,28 +55,40 @@ export type FlatRule = {
     tags: string[];
 };
 export declare function flattenStyleguides(guides: Styleguide[], filter?: string[]): FlatRule[];
+export type NewStyleRule = {
+    name: string;
+    description?: string;
+    examples?: {
+        from: string;
+        to: string;
+    }[];
+    tags?: string[];
+};
+export type NewWordlistEntry = {
+    term: string;
+    disallowed?: string[];
+    description?: string;
+    tags?: string[];
+};
+export type NewRule = NewStyleRule | NewWordlistEntry;
+export declare function resolveStyleguide(guides: Styleguide[], config: Config, override?: string): Styleguide;
+export type ResolvedSection = StyleguideSection & {
+    sectionId: string;
+};
+export declare function resolveSection(guide: Styleguide, kind: "rules" | "wordlist", override?: string, opts?: {
+    softKindFallback?: boolean;
+}): ResolvedSection;
 export declare class DittoApi {
     private readonly config;
     private readonly apiKey;
     constructor(config: Config, apiKey: string);
     getStyleguides(): Promise<Styleguide[]>;
-    getStyleguideInfo(styleguideOverride?: string): Promise<{
-        styleguideId: string;
-        sectionId: string;
-    } | null>;
-    createRule(opts: {
+    createRules(opts: {
         styleguideId: string;
         sectionId: string;
-        name: string;
-        description: string;
-        examples?: {
-            from: string;
-            to: string;
-        }[];
-        tags?: string[];
+        rules: NewRule[];
     }): Promise<{
-        id: string;
-        name: string;
+        ids: string[];
     }>;
     private fetch;
     private headers;

package/dist/api.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DittoApi = void 0;
 exports.flattenStyleguides = flattenStyleguides;
+exports.resolveStyleguide = resolveStyleguide;
+exports.resolveSection = resolveSection;
 function flattenStyleguides(guides, filter) {
     const selected = filter?.length
         ? guides.filter((g) => filter.includes(g.name) || filter.includes(g.developerId))
@@ -41,6 +43,53 @@ function flattenStyleguides(guides, filter) {
     }
     return result;
 }
+function resolveStyleguide(guides, config, override) {
+    if (guides.length === 0) {
+        throw new Error("No style guides found in this workspace. Create one on the Ditto platform first.");
+    }
+    const target = override ?? config.defaultStyleguide;
+    if (!target)
+        return guides[0];
+    const match = guides.find((g) => g.developerId === target || g.name === target);
+    if (!match) {
+        const available = guides.map((g) => `${g.developerId} (${g.name})`).join(", ");
+        throw new Error(`Style guide "${target}" not found. Available: ${available}`);
+    }
+    return match;
+}
+function resolveSection(guide, kind, override, 
+// With softKindFallback, an override that only matches sections of the other
+// kind falls back to the first section of the requested kind instead of
+// throwing — used for the --section default, which applies per kind.
+opts) {
+    const describe = (s) => s.sectionId ? `${s.sectionId} (${s.name}, ${s.kind})` : `${s.name} (${s.kind})`;
+    const withId = (s) => {
+        if (!s.sectionId) {
+            throw new Error(`Section "${s.name}" has no sectionId in the API response. ` +
+                "Rule creation needs an API that exposes sectionId on GET /v2/styleguides — the server may not be updated yet.");
+        }
+        return s;
+    };
+    if (override) {
+        const matches = guide.sections.filter((s) => s.sectionId === override || s.name === override);
+        if (matches.length === 0) {
+            const available = guide.sections.map(describe).join(", ") || "none";
+            throw new Error(`Section "${override}" not found in style guide "${guide.name}". Available: ${available}`);
+        }
+        const match = matches.find((s) => s.kind === kind);
+        if (match)
+            return withId(match);
+        if (!opts?.softKindFallback) {
+            throw new Error(`Section "${matches[0].name}" is a ${matches[0].kind} section, but the rules being created need a ${kind} section.`);
+        }
+    }
+    const match = guide.sections.find((s) => s.kind === kind);
+    if (!match) {
+        const available = guide.sections.map(describe).join(", ") || "none";
+        throw new Error(`Style guide "${guide.name}" has no ${kind} section. Available sections: ${available}`);
+    }
+    return withId(match);
+}
 class DittoApi {
     constructor(config, apiKey) {
         this.config = config;
@@ -52,41 +101,24 @@ class DittoApi {
         const data = (await res.json());
         return data.styleguides;
     }
-    async getStyleguideInfo(styleguideOverride) {
-        const guides = await this.getStyleguides();
-        if (guides.length === 0)
-            return null;
-        const target = styleguideOverride ?? this.config.defaultStyleguide;
-        let guide;
-        if (target) {
-            const match = guides.find((g) => g.developerId === target || g.name === target);
-            if (!match) {
-                const available = guides.map((g) => `${g.developerId} (${g.name})`).join(", ");
-                throw new Error(`Style guide "${target}" not found. Available: ${available}`);
-            }
-            guide = match;
-        }
-        else {
-            guide = guides[0];
-        }
-        if (guide.sections.length === 0)
-            return null;
-        const section = guide.sections.find((s) => s.kind === "rules") ?? guide.sections[0];
-        return { styleguideId: guide.developerId, sectionId: section.name };
-    }
-    async createRule(opts) {
-        const url = new URL(`/v2/styleguides/${encodeURIComponent(opts.styleguideId)}/rules`, this.config.apiBase);
+    async createRules(opts) {
+        const url = new URL("/v2/styleguides/rules", this.config.apiBase);
         const res = await this.fetch(url, {
             method: "POST",
             body: JSON.stringify({
+                styleguideId: opts.styleguideId,
                 sectionId: opts.sectionId,
-                name: opts.name,
-                description: opts.description,
-                examples: opts.examples,
-                tags: opts.tags,
+                rules: opts.rules,
             }),
         });
-        return (await res.json());
+        // Tolerate a response without a well-formed ids array (proxy body,
+        // contract drift): the rules were created — HTTP errors throw in fetch —
+        // so report success with whatever ids are usable rather than crashing.
+        const data = (await res.json().catch(() => null));
+        const ids = data && Array.isArray(data.ids) && data.ids.every((x) => typeof x === "string")
+            ? data.ids
+            : [];
+        return { ids };
     }
     async fetch(url, init) {
         const res = await fetch(url.toString(), {

package/dist/cli.js

@@ -1,11 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const check_1 = require("./commands/check");
-const create_rule_1 = require("./commands/create-rule");
+const create_rules_1 = require("./commands/create-rules");
 const init_1 = require("./commands/init");
 const list_1 = require("./commands/list");
 const pull_1 = require("./commands/pull");
+const rules_1 = require("./commands/rules");
 const scaffold_1 = require("./commands/scaffold");
+function getFlag(args, flag) {
+    const idx = args.indexOf(flag);
+    if (idx === -1)
+        return undefined;
+    const value = args[idx + 1];
+    if (value === undefined || value.startsWith("--")) {
+        process.stderr.write(`Missing value for ${flag}.\n`);
+        process.exit(2);
+    }
+    return value;
+}
 const COMMANDS = {
     init: async (args) => (0, init_1.init)({ writeAgent: args.includes("--agent"), force: args.includes("--force") }),
     pull: async (args) => (0, pull_1.pull)({ dryRun: args.includes("--dry-run") }),
@@ -17,22 +29,28 @@ const COMMANDS = {
             process.stderr.write("Usage: ditto-spec scaffold <ComponentName> [--path <dir>]\n");
             process.exit(2);
         }
-        const pathIdx = args.indexOf("--path");
-        const targetDir = pathIdx !== -1 && args[pathIdx + 1] ? args[pathIdx + 1] : process.cwd();
-        return (0, scaffold_1.scaffold)({ componentName: name, targetDir });
+        return (0, scaffold_1.scaffold)({ componentName: name, targetDir: getFlag(args, "--path") ?? process.cwd() });
     },
-    "create-rule": async (args) => {
-        function getFlag(flag) {
-            const idx = args.indexOf(flag);
-            return idx !== -1 && args[idx + 1] ? args[idx + 1] : undefined;
-        }
-        const name = getFlag("--name");
-        const description = getFlag("--description");
-        if (!name || !description) {
-            process.stderr.write('Usage: ditto-spec create-rule --name "<name>" --description "<desc>" [--styleguide "<name-or-id>"] [--tags "<t1,t2>"] [--examples \'<json>\']\n');
-            process.exit(2);
-        }
-        return (0, create_rule_1.createRule)({ name, description, styleguide: getFlag("--styleguide"), tags: getFlag("--tags"), examples: getFlag("--examples") });
+    rules: async (args) => {
+        return (0, rules_1.rules)({ styleguide: getFlag(args, "--styleguide") });
+    },
+    "create-rules": async (args) => {
+        return (0, create_rules_1.createRules)({
+            file: getFlag(args, "--file"),
+            styleguide: getFlag(args, "--styleguide"),
+            section: getFlag(args, "--section"),
+        });
+    },
+    // Removed in favor of create-rules; skill files generated by older CLI
+    // versions still invoke it, so fail with a pointer instead of "Unknown command".
+    "create-rule": async () => {
+        process.stderr.write("create-rule has been replaced by create-rules, which takes a JSON array of rules on stdin:\n\n" +
+            "  ditto-spec create-rules <<'EOF'\n" +
+            '  [{"name": "<rule name>", "description": "<desc>", "tags": ["tag1"], "examples": [{"from": "...", "to": "..."}]}]\n' +
+            "  EOF\n\n" +
+            "Run `ditto-spec --help` for the full input format, and\n" +
+            "`ditto-spec init --agent --force` to refresh skill files generated by an older version.\n");
+        process.exit(2);
     },
 };
 const HELP = `ditto-spec — sync .ditto.md content specs with the Ditto platform.
@@ -50,12 +68,18 @@ Commands:
   pull --dry-run   Show which files would change without writing.
   check            Parse every spec file; exit non-zero on any malformed file.
   list             Print every component spec with its surfaces and tags.
-  create-rule      Create a rule on the platform.
-    --name "<name>"              Rule name (required)
-    --description "<desc>"       Rule description (required)
+  rules            Print every rule on the platform, grouped by style guide and section.
+    --styleguide "<name-or-id>"  Limit to one style guide (optional)
+  create-rules     Create rules on the platform from a JSON array (stdin or --file).
+    Each rule is either a style rule {name, description?, examples?, tags?, section?}
+    or a terminology entry {term, disallowed?, description?, tags?, section?}.
+    A rule's "section" (name or id) maps it to an existing section of the style
+    guide; the section's kind must match the rule's shape ("rules" for style
+    rules, "wordlist" for terminology). Omitted: first section of matching kind.
+    --file <path>                Read the JSON array from a file instead of stdin
     --styleguide "<name-or-id>"  Target style guide (optional, overrides config)
-    --tags "<t1,t2>"             Comma-separated tags (optional)
-    --examples '<json>'          JSON array of {from,to} pairs (optional)
+    --section "<name-or-id>"     Default section for rules without their own (optional;
+                                 applies only to rules matching the section's kind)
 
 Environment:
   DITTO_API_KEY    Workspace API key (required for pull).

package/dist/commands/create-rules.d.ts

@@ -0,0 +1,7 @@
+interface CreateRulesOptions {
+    file?: string;
+    styleguide?: string;
+    section?: string;
+}
+export declare function createRules(opts: CreateRulesOptions): Promise<void>;
+export {};

package/dist/commands/create-rules.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRules = createRules;
+const node_fs_1 = require("node:fs");
+const api_1 = require("../api");
+const config_1 = require("../config");
+function readInput(file) {
+    if (file)
+        return (0, node_fs_1.readFileSync)(file, "utf8");
+    if (process.stdin.isTTY) {
+        throw new Error("No input. Pipe a JSON array of rules on stdin or pass --file <path>.\n" +
+            'Example: ditto-spec create-rules <<\'EOF\'\n[{"name": "Use sentence case", "description": "..."}]\nEOF');
+    }
+    return (0, node_fs_1.readFileSync)(0, "utf8");
+}
+function isStringArray(v) {
+    return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+function validateRule(rule, index) {
+    const at = `Rule at index ${index}`;
+    if (typeof rule !== "object" || rule === null || Array.isArray(rule)) {
+        throw new Error(`${at} must be an object.`);
+    }
+    const r = rule;
+    const hasName = typeof r.name === "string" && r.name.trim() !== "";
+    const hasTerm = typeof r.term === "string" && r.term.trim() !== "";
+    if (hasName === hasTerm) {
+        throw new Error(`${at} must have exactly one of "name" (style rule) or "term" (terminology entry).`);
+    }
+    if (r.description !== undefined && typeof r.description !== "string") {
+        throw new Error(`${at}: "description" must be a string.`);
+    }
+    if (r.tags !== undefined && !isStringArray(r.tags)) {
+        throw new Error(`${at}: "tags" must be an array of strings.`);
+    }
+    if (r.section !== undefined && (typeof r.section !== "string" || r.section.trim() === "")) {
+        throw new Error(`${at}: "section" must be a non-empty string (section name or sectionId).`);
+    }
+    const section = r.section;
+    if (hasName) {
+        if (r.disallowed !== undefined) {
+            throw new Error(`${at}: "disallowed" only applies to terminology entries (use "term", not "name").`);
+        }
+        if (r.examples !== undefined) {
+            const ok = Array.isArray(r.examples) &&
+                r.examples.every((e) => typeof e === "object" &&
+                    e !== null &&
+                    typeof e.from === "string" &&
+                    typeof e.to === "string");
+            if (!ok)
+                throw new Error(`${at}: "examples" must be an array of {from, to} string pairs.`);
+        }
+        return {
+            section,
+            rule: {
+                name: r.name,
+                description: r.description,
+                examples: r.examples,
+                tags: r.tags,
+            },
+        };
+    }
+    if (r.examples !== undefined) {
+        throw new Error(`${at}: "examples" only applies to style rules (use "name", not "term").`);
+    }
+    if (r.disallowed !== undefined && !isStringArray(r.disallowed)) {
+        throw new Error(`${at}: "disallowed" must be an array of strings.`);
+    }
+    return {
+        section,
+        rule: {
+            term: r.term,
+            disallowed: r.disallowed,
+            description: r.description,
+            tags: r.tags,
+        },
+    };
+}
+async function createRules(opts) {
+    const raw = readInput(opts.file);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("Input must be valid JSON.");
+    }
+    if (!Array.isArray(parsed) || parsed.length === 0) {
+        throw new Error("Input must be a non-empty JSON array of rules.");
+    }
+    const rules = parsed.map(validateRule);
+    const { config } = (0, config_1.loadConfig)();
+    const apiKey = (0, config_1.getApiKey)();
+    const api = new api_1.DittoApi(config, apiKey);
+    const guides = await api.getStyleguides();
+    const guide = (0, api_1.resolveStyleguide)(guides, config, opts.styleguide);
+    // Resolve every rule's section before creating anything, so a bad section
+    // fails the batch before any API writes (mid-batch API failures are handled
+    // below). A rule's own "section" must match its kind; the --section default
+    // applies only to rules of its kind — others get the first section of theirs.
+    const resolved = rules.map((input, index) => {
+        const kind = "name" in input.rule ? "rules" : "wordlist";
+        try {
+            const section = input.section
+                ? (0, api_1.resolveSection)(guide, kind, input.section)
+                : (0, api_1.resolveSection)(guide, kind, opts.section, { softKindFallback: true });
+            return { rule: input.rule, section };
+        }
+        catch (err) {
+            throw new Error(`Rule at index ${index}: ${err instanceof Error ? err.message : err}`);
+        }
+    });
+    // One API call per target section, preserving input order within each.
+    const groups = new Map();
+    for (const { rule, section } of resolved) {
+        const group = groups.get(section.sectionId) ?? { name: section.name, rules: [] };
+        group.rules.push(rule);
+        groups.set(section.sectionId, group);
+    }
+    const groupList = [...groups.entries()];
+    for (let g = 0; g < groupList.length; g++) {
+        const [sectionId, group] = groupList[g];
+        let result;
+        try {
+            result = await api.createRules({
+                styleguideId: guide.developerId,
+                sectionId,
+                rules: group.rules,
+            });
+        }
+        catch (err) {
+            // Earlier groups are already on the platform and there is no delete API;
+            // hand back exactly the rules that still need creating so a retry
+            // doesn't duplicate the ones that succeeded.
+            const created = groupList.slice(0, g).reduce((n, [, grp]) => n + grp.rules.length, 0);
+            const remaining = groupList
+                .slice(g)
+                .flatMap(([sid, grp]) => grp.rules.map((rule) => ({ ...rule, section: sid })));
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`${message}\n\n` +
+                (created > 0
+                    ? `${created} rule(s) were already created (see ✓ lines above) — do not resubmit them.\n`
+                    : "") +
+                `${remaining.length} rule(s) were NOT created. Re-run create-rules with exactly this input:\n` +
+                JSON.stringify(remaining, null, 2));
+        }
+        group.rules.forEach((rule, i) => {
+            const label = "name" in rule ? rule.name : rule.term;
+            const id = result.ids[i];
+            console.log(`✓ Created "${label}" in ${guide.name} › ${group.name}${id ? ` (${id})` : ""}`);
+        });
+        if (result.ids.length !== group.rules.length) {
+            console.log(`  ⚠ Server returned ${result.ids.length} id(s) for ${group.rules.length} rule(s) in "${group.name}" — ids above may be incomplete.`);
+        }
+    }
+}

package/dist/commands/init.js

@@ -207,8 +207,9 @@ function writeSkillFiles(cwd, force) {
         console.log(`  ${unchanged} skill file(s) already up to date.`);
     }
     if (skipped.length > 0) {
-        console.log(`⚠ Skipped ${skipped.length} locally modified skill file(s): ${skipped.join(", ")}`);
-        console.log("  Re-run with --force to overwrite.");
+        console.log(`⚠ Skipped ${skipped.length} skill file(s) that differ from the current templates: ${skipped.join(", ")}`);
+        console.log("  These may be locally modified, or generated by an older CLI version.");
+        console.log("  Re-run with --force to overwrite them with the current versions.");
     }
 }
 function printAgentSuggestions(env) {

package/dist/commands/rules.d.ts

@@ -0,0 +1,5 @@
+interface RulesOptions {
+    styleguide?: string;
+}
+export declare function rules(opts: RulesOptions): Promise<void>;
+export {};

package/dist/commands/rules.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rules = rules;
+const api_1 = require("../api");
+const config_1 = require("../config");
+async function rules(opts) {
+    const { config } = (0, config_1.loadConfig)();
+    const apiKey = (0, config_1.getApiKey)();
+    const api = new api_1.DittoApi(config, apiKey);
+    const guides = await api.getStyleguides();
+    // With an explicit override, resolveStyleguide never falls back to
+    // config.defaultStyleguide — no override still lists every guide.
+    const selected = opts.styleguide ? [(0, api_1.resolveStyleguide)(guides, config, opts.styleguide)] : guides;
+    for (const guide of selected) {
+        const locale = guide.variant?.localeCode ? ` [locale: ${guide.variant.localeCode}]` : "";
+        console.log(`${guide.name} (${guide.developerId})${locale}`);
+        for (const section of guide.sections) {
+            const sectionId = section.sectionId ? ` (sectionId: ${section.sectionId})` : "";
+            console.log(`  ${section.name} [${section.kind}]${sectionId}`);
+            if (section.rules.length === 0)
+                console.log("    (no rules)");
+            for (const rule of section.rules) {
+                if (section.kind === "rules") {
+                    const r = rule;
+                    const tags = r.tags.length > 0 ? ` — tags: ${r.tags.join(", ")}` : "";
+                    console.log(`    - ${r.name}${tags}`);
+                    if (r.description)
+                        console.log(`      ${r.description}`);
+                }
+                else {
+                    const r = rule;
+                    const disallowed = r.disallowed.length > 0 ? ` (not: ${r.disallowed.join(", ")})` : "";
+                    const tags = r.tags.length > 0 ? ` — tags: ${r.tags.join(", ")}` : "";
+                    console.log(`    - ${r.term}${disallowed}${tags}`);
+                    if (r.description)
+                        console.log(`      ${r.description}`);
+                }
+            }
+        }
+        console.log("");
+    }
+}

package/dist/skills.d.ts

@@ -1,4 +1,4 @@
 export declare const SKILL_SPEC_COMPONENT = "---\ndescription: Analyze a component, create ditto specs for it and its dependencies, and auto-fill surfaces and tags\nargument-hint: <ComponentName or path/to/component>\nallowed-tools: [Read, Bash, Edit, Write, Grep, Glob, Agent]\n---\n\n# Spec Component\n\nAnalyze a design system component, scaffold `.ditto.md` content specs (including child components that lack specs), auto-fill surfaces and tags, and sync rules from the platform.\n\n## Input\n\n$ARGUMENTS\n\nAccept either a component name (e.g. `Button`) or a file path (e.g. `src/components/Button/index.tsx`). If a name is given, search the codebase to find the component. If multiple matches exist, ask the user to clarify.\n\n---\n\n## Phase 1: Discovery\n\nFind the target component and map its dependencies.\n\n1. Locate the component source file.\n2. Read the component code. Walk imports to find **child components that render user-facing text** (components that accept string props, children rendered as text, or contain hardcoded strings). Skip utility imports, style imports, icon imports, and non-text components.\n3. Check which components already have an `index.ditto.md` spec by looking for the file in each component's directory.\n4. Read `workspace.ditto.md` at the project root (if it exists) for existing platform tags and universal rules.\n5. Report:\n   - Target component and its location\n   - Whether the target already has a spec (and what surfaces it declares)\n   - Child components needing specs (no existing `index.ditto.md`)\n   - Existing specs found (already covered)\n\n---\n\n## Phase 2: Surface Analysis\n\nFor each component that needs a new spec (target + unspecced children):\n\n1. Read the TypeScript interface / props type definition.\n2. Identify every **text surface** \u2014 each piece of user-facing copy the component renders:\n   - **String props** rendered in JSX \u2192 use the prop name as the surface key\n   - **`children`** when used as text \u2192 use `$children` as the surface key\n   - **Nested props** \u2192 use dot notation (e.g. `primaryAction.label`)\n   - **Hardcoded strings** in JSX \u2192 use a descriptive role name (e.g. `headline`, `submitLabel`, `bodyText`)\n3. For each surface, suggest **tags** from the `workspace.ditto.md` tag inventory, matched by semantic role (e.g. `heading`, `body`, `button`, `call-to-action`). Prefer reusing existing tags. Only propose a new tag if nothing fits \u2014 and note it will be new.\n4. Estimate **`maxLength`** where layout context provides constraints (e.g. single-line headings, button widths). Omit if no clear constraint.\n\n**If the component already has a spec**, compare the existing surfaces against what the code declares. Report any new surfaces that aren't in the spec yet, and any spec surfaces that no longer exist in the code. Propose additions/removals.\n\nPresent the proposed spec for each component in exact YAML format:\n\n```yaml\n---\ncomponent: ComponentName\ntags: [relevant-tags]\nsurfaces:\n  surfaceKey:\n    tags: [semantic-tags]\n    maxLength: 60\n# Managed by Ditto \u2014 do not edit below\nrules: []\n---\n```\n\n**STOP HERE. Ask the user to review and approve the proposed surfaces before creating or modifying any files.** Let them add, remove, or modify surfaces and tags.\n\n---\n\n## Phase 3: Create or Update Specs\n\nAfter user approval:\n\n**For new specs:**\n\n1. Run:\n   ```\n   npx ditto-spec scaffold <ComponentName> --path <component-directory>\n   ```\n2. Edit each created `index.ditto.md` to replace the empty `surfaces: {}` and `tags: []` with the approved values. Only edit developer-owned keys (`component`, `tags`, `surfaces`). Never write `rules` or `locales` by hand.\n\n**For existing specs getting new surfaces:**\n\n1. Edit the existing `index.ditto.md` to add the approved new surfaces and tags.\n\n**Then for all specs (new and updated):**\n\n3. Run `npx ditto-spec pull` to populate the `rules` and `locales` sections from the platform.\n4. Run `npx ditto-spec check` to validate all spec files.\n\nReport which specs were created/updated and how many rules were pulled.\n\n---\n\n## Reference: Ditto Spec Conventions\n\n- **Surface keys**: prop name for props, `$children` for children text, dot-notation for nested props (`primaryAction.label`), descriptive role for hardcoded strings (`headline`, `bodyText`).\n- **Tags**: lowercase, hyphenated. Match semantic role (e.g. `heading`, `body`, `button`, `call-to-action`, `dialog-title`). Check `workspace.ditto.md` `tags` key for the full inventory.\n- **Developer-owned keys**: `component`, `tags`, `surfaces` \u2014 edit freely.\n- **CLI-managed keys**: `rules`, `locales` (and workspace `tags`) \u2014 **never write by hand**. Populated by `ditto-spec pull`.\n- **Rule shapes**: style rules have `name`, `description`, optional `examples`, and `section`. Terminology entries have `term`, `disallowed`, `description`, and `section`.\n- **Locale-scoped rules**: the `locales` key contains rules keyed by locale code (e.g. `de-DE`). These apply in addition to base `rules` when writing for that locale.\n- **Rule hierarchy**: workspace rules (apply everywhere) \u2192 component-level rules (no `surface` field) \u2192 per-surface rules (with `surface: \"<key>\"`). Locale-scoped rules follow the same hierarchy.\n- **Parent-child layering**: if a parent passes text to a child, the parent declares a surface in its own spec. A child having its own spec does NOT exempt the parent from declaring surfaces for text it provides.\n- **Tag matching**: rules match specs by tag intersection. Any shared tag triggers the match.\n";
 export declare const SKILL_SPEC_AUDIT = "---\ndescription: Audit component copy against ditto spec rules and report violations\nargument-hint: <ComponentName or path> (optional \u2014 omit to audit all)\nallowed-tools: [Read, Bash, Grep, Glob, Agent]\n---\n\n# Spec Audit\n\nEvaluate user-facing copy in component instances against the rules in their `.ditto.md` specs. Reports violations with file locations and suggested corrections.\n\n## Input\n\n$ARGUMENTS\n\nIf a component name or path is given, audit only that component. If omitted, audit all components that have specs.\n\n---\n\n## Phase 1: Load Specs\n\n1. Read `workspace.ditto.md` at the project root for workspace-level rules, tags, and locale-scoped rules.\n2. If a specific component was given, find its `index.ditto.md`. If auditing all, run `npx ditto-spec list` to discover all specced components, then read each `index.ditto.md`.\n3. For each component, build the full rule set:\n   - Workspace rules (apply to all surfaces)\n   - Component-level rules (no `surface` field \u2014 apply to all surfaces in this component)\n   - Per-surface rules (with `surface: \"<key>\"` \u2014 apply only to that surface)\n   - Locale-scoped rules from `locales` (if present, at workspace or component level)\n\n---\n\n## Phase 2: Find & Resolve Instances\n\n1. Search the codebase for all files that import and render each component being audited.\n2. For each instance, evaluate the **actual copy** bound to **every** text surface. A surface's value may be an inline literal or a reference to a string stored elsewhere \u2014 and a single instance commonly mixes both. These layers are **not** mutually exclusive: evaluate every one that applies, and resolving an externalized source never lets you skip the inline copy.\n\n   **a. Inline (always \u2014 the baseline).** Read and audit the literal text present directly in the code: string literals and template strings passed as props, children rendered as text, hardcoded strings in the component/JSX, and variables with obvious values (trace one level if needed). **This pass is mandatory and is never skipped \u2014 auditing hardcoded copy is the default job of this skill, so do it for every instance even when the component also uses i18n or Ditto.**\n\n   **b. i18n key** \u2014 the surface is bound to a translation lookup such as `t('dialog.headline')`, `i18n.t(...)`, `$t('key')`, `<FormattedMessage id=\"...\">`, `intl.formatMessage({ id })`, `<Trans i18nKey=\"...\">`, or a Rails `t('.key')`. Resolve it:\n      - Locate the catalog file(s) by convention (see **Resolving copy sources** below) and look up the key, supporting nested/dot keys and namespaces.\n      - Resolve the value in **every** available locale catalog, not just the default. Each locale's value is a separate instance to evaluate, and it activates that locale's `locales.<code>` rules.\n      - Resolve **plural forms** (i18next `_one`/`_other`/`_zero`/`_many`, ICU `{count, plural, \u2026}`, `.stringsdict`, Android `<plurals>`) \u2014 evaluate each form.\n      - Treat **interpolation placeholders** (`{{var}}`, `{var}`, `%s`, `%@`, `%1$s`, ICU `{name}`) as opaque tokens \u2014 audit the copy around them, never the token.\n\n   **c. Ditto text item** \u2014 the surface resolves to a string Ditto manages, fetched through a key-lookup call. **The deciding signal is key-resolvability, not the function name:** whenever a surface is bound to any lookup-style call passing a string literal (e.g. `getDittoText('open-in-figma')`, `t('style-guides')`, `ditto.t(...)`, `getText('...')`) that the inline (**a**) and i18n (**b**) branches did not already resolve, treat the literal as a candidate Ditto **Developer ID** and try to resolve it. An accessor name containing \"ditto\" (case-insensitive \u2014 `getDittoText`, `useDittoText`, `dittoText`, `ditto.t`) or an import tracing to a Ditto module is a corroborating hint, not a requirement.\n      - Locate the Ditto output: the `ditto/` folder, or the `outDir` in `ditto/config.yml`.\n      - **Grep the specific literal id as a key** across the `{project}___{variant}.json` and `components__{variant}.json` files \u2014 do not read whole files or index all keys. Prefer an exact key match; only if none exists, try a normalized (kebab/camel) form of the id.\n      - If the key is found, it **is** a Ditto text item: resolve its value in **every** variant file that contains it (each variant is a separate instance, parallel to the every-locale rule in **b**; infer the variant/locale from the file name), resolve `_one`/`_other` plural forms (evaluate each), and treat `{{variableId}}` placeholders as opaque tokens. Record the source as **Ditto**, naming the Developer ID and variant.\n      - If the id is **not a string literal** (e.g. `getDittoText('item-' + type)`) or **no ditto file contains the key**, drop to **d** \u2014 never log a Ditto source you could not key-match.\n\n   **d. Unresolvable / dynamic** \u2014 the value is computed at runtime, the key is itself a variable (e.g. `t('item.' + type)`), the key or catalog can't be found, or the string is assembled from fragments. **Never skip silently.** Evaluate whatever is statically knowable (literal fragments, the message skeleton) and record an explicit **unresolved \u2014 manual review** entry naming the surface, the binding you found, and why it could not be resolved.\n\nThis skill **reads** from every source but **never modifies any of them** \u2014 inline code, i18n catalogs, and Ditto text items are each owned by their own workflow. Auditing is report-only.\n\n---\n\n## Phase 3: Evaluate\n\nFor each instance, evaluate the copy against every applicable rule:\n\n- **Style rules** (`name`/`description`/`examples`): check that copy follows the described guidance. Use `examples` (before/after pairs) as concrete reference for tone, length, and shape.\n- **Terminology entries** (`term`/`disallowed`): check that copy uses the `term` form and never uses any `disallowed` alternative. Check all surface text, not just exact matches \u2014 look for the disallowed forms appearing within longer strings.\n- **`maxLength` / `minLength`**: flag any text that exceeds or falls short of the constraint.\n- **Locale-scoped rules**: when a resolved string comes from a specific locale (identifiable from its catalog file path/name, i18n key, Ditto variant, or surrounding context), also evaluate it against the matching `locales.<code>` rules, in addition to the base rules.\n- **Interpolation placeholders**: treat `{{var}}`, `{var}`, `%s`, `%@`, `%1$s`, and ICU `{name}` tokens as opaque \u2014 evaluate the copy around them, not the token itself.\n\nEach rule carries a `section` field (e.g. \"Voice & Tone\", \"Terminology\") \u2014 use this to group violations in the report.\n\n---\n\n## Phase 4: Report\n\nPresent violations grouped by component, then by file:\n\nFor each violation:\n- **File and line** where the instance appears\n- **Surface** the text maps to\n- **Source** where the copy lives: `inline (code)`, `i18n catalog: <file>#<key> [locale]`, or `ditto text item: <developer-id> [variant]`\n- **Text** that violates the rule\n- **Rule** that is violated (name or term, plus section)\n- **Suggested correction** \u2014 for inline copy this is a code change; for i18n catalogs and Ditto text items it is **advisory only**: the string is owned by that workflow and must be changed there, not edited in component code. Never present it as a code edit, and never modify the catalog or text item.\n\nIf no violations are found, say so explicitly \u2014 a clean audit is useful information.\n\nEnd with a summary: total components audited, total instances checked, total violations found. If any surfaces could not be resolved (Phase 2d), list them under **Unresolved surfaces** with their bindings \u2014 never let a resolution gap pass silently.\n\n---\n\n## Reference: Resolving copy sources\n\nConventions for locating externally-stored copy. Infer the **locale** from the file path or name (e.g. `de-DE`, `/de/`, `__spanish`, `values-de/`) so locale-scoped rules apply.\n\n- **Ditto** \u2014 `ditto/` (or the `outDir` in `ditto/config.yml`); files `{project}___{variant}.json`, `components__{variant}.json`, plus `variables.json`. Keys are Developer IDs; plurals use `_one`/`_other` suffixes; variables are `{{variableId}}`. Output may also be Android XML or iOS `.strings`/`.stringsdict`. **Detect Ditto bindings by key-resolvability, not function name:** any string-literal argument to a lookup-style call (whatever it's named) that matches a Developer-ID key in these files is a Ditto text item. Grep the specific id as a key \u2014 never read entire files to find it.\n- **i18next / react-intl / FormatJS** \u2014 `locales/`, `public/locales/<lng>/<ns>.json`, `i18n/`, `lang/`, `messages.*.json`.\n- **Flutter** \u2014 `.arb` files. **gettext** \u2014 `.po`/`.pot`. **Rails** \u2014 `config/locales/*.yml`. **Apple** \u2014 `*.strings`, `*.stringsdict`, `*.xcstrings`. **Android** \u2014 `res/values*/strings.xml`.\n\nWhen key resolution is ambiguous (e.g. multiple catalogs or namespaces in a monorepo), prefer the catalog nearest the importing instance or matching the configured namespace; if still ambiguous, mark the surface unresolved (Phase 2d) rather than guessing. Look copy up by key \u2014 do not read entire catalogs into context.\n\n---\n\n## Reference: Ditto Spec Conventions\n\n- **Rule shapes**: style rules have `name`, `description`, optional `examples`, and `section`. Terminology entries have `term`, `disallowed`, `description`, and `section`.\n- **Locale-scoped rules**: the `locales` key contains rules keyed by locale code (e.g. `de-DE`). These apply in addition to base `rules` when writing for that locale.\n- **Rule hierarchy**: workspace rules (apply everywhere) \u2192 component-level rules (no `surface` field) \u2192 per-surface rules (with `surface: \"<key>\"`). Locale-scoped rules follow the same hierarchy.\n- **Tag matching**: rules match specs by tag intersection. Any shared tag triggers the match. If a rule matches both component-level and surface-level tags, it emits at component level (broader scope wins).\n";
-export declare const SKILL_SPEC_GAPS = "---\ndescription: Analyze copy across component instances to find rule gaps, then create new rules on the platform\nargument-hint: <ComponentName or path> (optional \u2014 omit to analyze all)\nallowed-tools: [Read, Bash, Edit, Grep, Glob, Agent]\n---\n\n# Spec Gaps\n\nIdentify copy patterns in component instances that should be rules but aren't. Propose new style rules or terminology entries, and create approved ones on the Ditto platform.\n\n## Input\n\n$ARGUMENTS\n\nIf a component name or path is given, analyze only that component's instances. If omitted, analyze all components that have specs.\n\n---\n\n## Phase 1: Load Existing Rules\n\n1. Read `workspace.ditto.md` for workspace-level rules and tags.\n2. Read each relevant component's `index.ditto.md` for component-level and per-surface rules.\n3. Build a complete picture of what's already covered \u2014 every style rule, terminology entry, and locale-scoped rule currently in the spec files.\n\n---\n\n## Phase 2: Analyze Copy\n\n1. Search the codebase for **instances where each component is used** \u2014 find all files that import and render it.\n2. For each instance, gather the **actual copy** bound to **every** text surface \u2014 inline and externalized alike. An instance often mixes both, so never skip the inline copy just because some surfaces resolve to a catalog:\n   - **Inline (always \u2014 the baseline).** String literals, template strings, children, hardcoded strings, and variables with obvious values. Always gather these; hardcoded copy is the default and is never skipped.\n   - **i18n key** \u2014 a lookup like `t('key')`, `<FormattedMessage id=\"...\">`, or `$t('key')`: resolve the key in the catalog file(s) (`locales/`, `public/locales/<lng>/<ns>.json`, `.arb`, `.po`, `config/locales/*.yml`, `*.strings`, `res/values*/strings.xml`), across **all** locales, including plural forms. Look copy up by key \u2014 do not read entire catalogs into context.\n   - **Ditto text item** \u2014 any lookup-style call passing a string literal (e.g. `getDittoText('id')`, `t('id')`, `ditto.t`) whose id matches a Developer-ID key in the project's Ditto output (`ditto/` folder, or `outDir` in `ditto/config.yml`; `{project}___{variant}.json` keyed by Developer ID, plurals suffixed `_one`/`_other`, variables `{{variableId}}`). Detect by key-resolvability, not function name; a \"ditto\"-ish name or import is just a hint. Grep the specific id as a key \u2014 do not read entire catalogs \u2014 and resolve per variant. If the id isn't a literal or no file has the key, treat as unresolvable.\n   - **Unresolvable / dynamic** \u2014 runtime-computed values or missing keys: analyze what is statically knowable and skip the rest. This skill only **reads** these sources; it never modifies catalogs or text items.\n3. Analyze the copy across all instances for patterns no existing rule covers:\n   - **Terminology inconsistencies**: the same concept referred to with different forms (e.g. \"sign up\" vs \"signup\" vs \"sign-up\"). These should become terminology entries.\n   - **Tone mismatches**: some instances formal, others casual. These should become style rules.\n   - **Anti-patterns**: passive voice in CTAs, overly long descriptions, redundant words.\n   - **Surface-specific conventions** that should be formalized (e.g. \"all action buttons start with a verb\").\n\n---\n\n## Phase 3: Propose Rules\n\nIf **no meaningful gaps** are found, say so and stop.\n\nIf gaps are found, propose new rules. Rules come in two shapes:\n\n**Style rules:**\n- **name**: short rule name\n- **description**: what the rule enforces\n- **tags**: which tags it should apply to (determines which surfaces it matches)\n- **examples**: `{from, to}` pairs drawn from actual code showing the pattern\n\n**Terminology entries:**\n- **term**: the canonical form\n- **disallowed**: list of variant forms to reject\n- **description**: why this form is preferred\n- **tags**: which tags it should apply to\n\nIf any proposed tags don't exist in the workspace yet, warn the user. Only existing workspace tags can be assigned to rules.\n\n**STOP HERE. Present proposals and ask the user which rules (if any) to create.**\n\n---\n\n## Phase 4: Create Rules\n\nBefore creating any rules, determine which style guide to target:\n\n1. Check `dittospec.config.json` for a `defaultStyleguide` value.\n2. If present, tell the user which style guide will be used and ask for confirmation.\n3. If absent (or the user wants a different one), ask the user for the exact style guide name to create the rules in \u2014 it must match a style guide that exists in the workspace (visible on the Ditto platform). `create-rule` rejects an unrecognized `--styleguide` value and lists the valid names, so a wrong name fails loudly instead of silently targeting the wrong guide.\n\nFor each approved rule, run:\n\n```\nnpx ditto-spec create-rule --name \"<rule name>\" --description \"<description>\" --styleguide \"<chosen style guide>\" --tags \"<tag1,tag2>\" --examples '<json array of {from,to}>'\n```\n\nIf a rule uses tags that don't exist yet, warn the user and omit those tags from the command.\n\nAfter all rules are created:\n\n1. Run `npx ditto-spec pull` to sync the new rules into spec files.\n2. Read the updated `index.ditto.md` files and verify the new rules appear.\n3. Report which rules were created and which specs they landed in.\n\n---\n\n## Reference: Ditto Spec Conventions\n\n- **Rule shapes**: style rules have `name`, `description`, optional `examples`, and `section`. Terminology entries have `term`, `disallowed`, `description`, and `section`.\n- **CLI-managed keys**: `rules`, `locales` (and workspace `tags`) \u2014 **never write by hand**. Populated by `ditto-spec pull`.\n- **Tag matching**: rules match specs by tag intersection. Any shared tag triggers the match. Rules with no tags are workspace-universal (apply to all surfaces).\n- **Rule hierarchy**: workspace rules (apply everywhere) \u2192 component-level rules (no `surface` field) \u2192 per-surface rules (with `surface: \"<key>\"`).\n";
+export declare const SKILL_SPEC_GAPS = "---\ndescription: Analyze copy across component instances to find rule gaps, then create new rules on the platform\nargument-hint: <ComponentName or path> (optional \u2014 omit to analyze all)\nallowed-tools: [Read, Bash, Edit, Grep, Glob, Agent]\n---\n\n# Spec Gaps\n\nIdentify copy patterns in component instances that should be rules but aren't. Propose new style rules or terminology entries, and create approved ones on the Ditto platform.\n\n## Input\n\n$ARGUMENTS\n\nIf a component name or path is given, analyze only that component's instances. If omitted, analyze all components that have specs.\n\n---\n\n## Phase 1: Load Existing Rules\n\n1. Read `workspace.ditto.md` for workspace-level rules and tags.\n2. Read each relevant component's `index.ditto.md` for component-level and per-surface rules.\n3. Run `npx ditto-spec rules` to load the **complete** platform rule set. Spec files only contain rules whose tags match a local component \u2014 a platform rule with non-matching tags is invisible in specs, and proposing a duplicate of it would be a mistake. The output also shows each style guide's sections (name, kind, sectionId), which Phase 4 may need.\n4. Build a complete picture of what's already covered \u2014 every style rule, terminology entry, and locale-scoped rule on the platform.\n\n---\n\n## Phase 2: Analyze Copy\n\n1. Search the codebase for **instances where each component is used** \u2014 find all files that import and render it.\n2. For each instance, gather the **actual copy** bound to **every** text surface \u2014 inline and externalized alike. An instance often mixes both, so never skip the inline copy just because some surfaces resolve to a catalog:\n   - **Inline (always \u2014 the baseline).** String literals, template strings, children, hardcoded strings, and variables with obvious values. Always gather these; hardcoded copy is the default and is never skipped.\n   - **i18n key** \u2014 a lookup like `t('key')`, `<FormattedMessage id=\"...\">`, or `$t('key')`: resolve the key in the catalog file(s) (`locales/`, `public/locales/<lng>/<ns>.json`, `.arb`, `.po`, `config/locales/*.yml`, `*.strings`, `res/values*/strings.xml`), across **all** locales, including plural forms. Look copy up by key \u2014 do not read entire catalogs into context.\n   - **Ditto text item** \u2014 any lookup-style call passing a string literal (e.g. `getDittoText('id')`, `t('id')`, `ditto.t`) whose id matches a Developer-ID key in the project's Ditto output (`ditto/` folder, or `outDir` in `ditto/config.yml`; `{project}___{variant}.json` keyed by Developer ID, plurals suffixed `_one`/`_other`, variables `{{variableId}}`). Detect by key-resolvability, not function name; a \"ditto\"-ish name or import is just a hint. Grep the specific id as a key \u2014 do not read entire catalogs \u2014 and resolve per variant. If the id isn't a literal or no file has the key, treat as unresolvable.\n   - **Unresolvable / dynamic** \u2014 runtime-computed values or missing keys: analyze what is statically knowable and skip the rest. This skill only **reads** these sources; it never modifies catalogs or text items.\n3. Analyze the copy across all instances for patterns no existing rule covers:\n   - **Terminology inconsistencies**: the same concept referred to with different forms (e.g. \"sign up\" vs \"signup\" vs \"sign-up\"). These should become terminology entries.\n   - **Tone mismatches**: some instances formal, others casual. These should become style rules.\n   - **Anti-patterns**: passive voice in CTAs, overly long descriptions, redundant words.\n   - **Surface-specific conventions** that should be formalized (e.g. \"all action buttons start with a verb\").\n\n---\n\n## Phase 3: Propose Rules\n\nIf **no meaningful gaps** are found, say so and stop.\n\nIf gaps are found, propose new rules. Rules come in two shapes:\n\n**Style rules:**\n- **name**: short rule name\n- **description**: what the rule enforces\n- **tags**: which tags it should apply to (determines which surfaces it matches)\n- **examples**: `{from, to}` pairs drawn from actual code showing the pattern\n- **section**: which existing section of the style guide it belongs in (pick from the sections shown by `npx ditto-spec rules` \u2014 e.g. a button rule belongs alongside other UI-pattern rules, not in a generic first section)\n\n**Terminology entries:**\n- **term**: the canonical form\n- **disallowed**: list of variant forms to reject\n- **description**: why this form is preferred\n- **tags**: which tags it should apply to\n- **section**: which existing wordlist section it belongs in\n\nIf any proposed tags don't exist in the workspace yet, warn the user. Only existing workspace tags can be assigned to rules.\n\n**STOP HERE. Present proposals and ask the user which rules (if any) to create.**\n\n---\n\n## Phase 4: Create Rules\n\nBefore creating any rules, determine which style guide to target:\n\n1. Check `dittospec.config.json` for a `defaultStyleguide` value.\n2. If present, tell the user which style guide will be used and ask for confirmation.\n3. If absent (or the user wants a different one), ask the user for the exact style guide name to create the rules in \u2014 it must match a style guide that exists in the workspace (visible on the Ditto platform). `create-rules` rejects an unrecognized `--styleguide` value and lists the valid names, so a wrong name fails loudly instead of silently targeting the wrong guide.\n\nCreate **all** approved rules in one invocation, piping a JSON array on stdin with a quoted heredoc (the quoted `'EOF'` delimiter keeps apostrophes and quotes in copy examples intact \u2014 never inline the JSON as a shell argument):\n\n```\nnpx ditto-spec create-rules --styleguide \"<chosen style guide>\" <<'EOF'\n[\n  {\"name\": \"<rule name>\", \"description\": \"<description>\", \"tags\": [\"tag1\"], \"examples\": [{\"from\": \"...\", \"to\": \"...\"}], \"section\": \"<existing section>\"},\n  {\"term\": \"<canonical form>\", \"disallowed\": [\"variant1\", \"variant2\"], \"description\": \"<why>\", \"tags\": [\"tag1\"], \"section\": \"<existing wordlist section>\"}\n]\nEOF\n```\n\nStyle rules (`name`) and terminology entries (`term`) can be mixed in one batch. Each rule's `section` (name or sectionId, as shown by `npx ditto-spec rules`) maps it to an existing section of the style guide; a rule's section kind must match its shape (`rules` sections for style rules, `wordlist` sections for terminology). If `section` is omitted, the rule lands in the first section of the matching kind.\n\nIf a rule uses tags that don't exist yet, warn the user and omit those tags from the JSON.\n\nAfter all rules are created:\n\n1. Run `npx ditto-spec pull` to sync the new rules into spec files.\n2. Read the updated `index.ditto.md` files and verify the new rules appear.\n3. Report which rules were created and which specs they landed in.\n\n---\n\n## Reference: Ditto Spec Conventions\n\n- **Rule shapes**: style rules have `name`, `description`, optional `examples`, and `section`. Terminology entries have `term`, `disallowed`, `description`, and `section`.\n- **CLI-managed keys**: `rules`, `locales` (and workspace `tags`) \u2014 **never write by hand**. Populated by `ditto-spec pull`.\n- **Tag matching**: rules match specs by tag intersection. Any shared tag triggers the match. Rules with no tags are workspace-universal (apply to all surfaces).\n- **Rule hierarchy**: workspace rules (apply everywhere) \u2192 component-level rules (no `surface` field) \u2192 per-surface rules (with `surface: \"<key>\"`).\n";
 export declare const SKILLS: Record<string, string>;

package/dist/skills.js

@@ -234,7 +234,8 @@ If a component name or path is given, analyze only that component's instances. I
 
 1. Read \`workspace.ditto.md\` for workspace-level rules and tags.
 2. Read each relevant component's \`index.ditto.md\` for component-level and per-surface rules.
-3. Build a complete picture of what's already covered — every style rule, terminology entry, and locale-scoped rule currently in the spec files.
+3. Run \`npx ditto-spec rules\` to load the **complete** platform rule set. Spec files only contain rules whose tags match a local component — a platform rule with non-matching tags is invisible in specs, and proposing a duplicate of it would be a mistake. The output also shows each style guide's sections (name, kind, sectionId), which Phase 4 may need.
+4. Build a complete picture of what's already covered — every style rule, terminology entry, and locale-scoped rule on the platform.
 
 ---
 
@@ -265,12 +266,14 @@ If gaps are found, propose new rules. Rules come in two shapes:
 - **description**: what the rule enforces
 - **tags**: which tags it should apply to (determines which surfaces it matches)
 - **examples**: \`{from, to}\` pairs drawn from actual code showing the pattern
+- **section**: which existing section of the style guide it belongs in (pick from the sections shown by \`npx ditto-spec rules\` — e.g. a button rule belongs alongside other UI-pattern rules, not in a generic first section)
 
 **Terminology entries:**
 - **term**: the canonical form
 - **disallowed**: list of variant forms to reject
 - **description**: why this form is preferred
 - **tags**: which tags it should apply to
+- **section**: which existing wordlist section it belongs in
 
 If any proposed tags don't exist in the workspace yet, warn the user. Only existing workspace tags can be assigned to rules.
 
@@ -284,15 +287,22 @@ Before creating any rules, determine which style guide to target:
 
 1. Check \`dittospec.config.json\` for a \`defaultStyleguide\` value.
 2. If present, tell the user which style guide will be used and ask for confirmation.
-3. If absent (or the user wants a different one), ask the user for the exact style guide name to create the rules in — it must match a style guide that exists in the workspace (visible on the Ditto platform). \`create-rule\` rejects an unrecognized \`--styleguide\` value and lists the valid names, so a wrong name fails loudly instead of silently targeting the wrong guide.
+3. If absent (or the user wants a different one), ask the user for the exact style guide name to create the rules in — it must match a style guide that exists in the workspace (visible on the Ditto platform). \`create-rules\` rejects an unrecognized \`--styleguide\` value and lists the valid names, so a wrong name fails loudly instead of silently targeting the wrong guide.
 
-For each approved rule, run:
+Create **all** approved rules in one invocation, piping a JSON array on stdin with a quoted heredoc (the quoted \`'EOF'\` delimiter keeps apostrophes and quotes in copy examples intact — never inline the JSON as a shell argument):
 
 \`\`\`
-npx ditto-spec create-rule --name "<rule name>" --description "<description>" --styleguide "<chosen style guide>" --tags "<tag1,tag2>" --examples '<json array of {from,to}>'
+npx ditto-spec create-rules --styleguide "<chosen style guide>" <<'EOF'
+[
+  {"name": "<rule name>", "description": "<description>", "tags": ["tag1"], "examples": [{"from": "...", "to": "..."}], "section": "<existing section>"},
+  {"term": "<canonical form>", "disallowed": ["variant1", "variant2"], "description": "<why>", "tags": ["tag1"], "section": "<existing wordlist section>"}
+]
+EOF
 \`\`\`
 
-If a rule uses tags that don't exist yet, warn the user and omit those tags from the command.
+Style rules (\`name\`) and terminology entries (\`term\`) can be mixed in one batch. Each rule's \`section\` (name or sectionId, as shown by \`npx ditto-spec rules\`) maps it to an existing section of the style guide; a rule's section kind must match its shape (\`rules\` sections for style rules, \`wordlist\` sections for terminology). If \`section\` is omitted, the rule lands in the first section of the matching kind.
+
+If a rule uses tags that don't exist yet, warn the user and omit those tags from the JSON.
 
 After all rules are created:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dittowords/spec-cli",
-  "version": "0.0.1-alpha.14",
+  "version": "0.0.1-alpha.15",
   "description": "CLI for syncing .ditto.md content specs with the Ditto platform.",
   "main": "dist/cli.js",
   "bin": {
@@ -10,7 +10,8 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && npm run sync-skills -- --check",
+    "sync-skills": "tsx scripts/sync-skills.ts",
     "prepublishOnly": "npm run build",
     "ditto-spec": "tsx src/cli.ts"
   },