@cruxy/cli 0.2.0 → 0.4.0

package/dist/skills/parser.d.ts

@@ -0,0 +1,31 @@
+import { CruxyError } from "../errors/index.js";
+import { type SkillFrontmatter } from "./types.js";
+/**
+ * Thrown when a SKILL.md is malformed or fails validation. A {@link CruxyError}
+ * (code CRUXY_E_SKILL_INVALID) so it carries a stable code if it reaches the
+ * boundary; the loader still catches it to record a `SkillError` and exclude the
+ * skill — loud, never silently skipped.
+ */
+export declare class SkillValidationError extends CruxyError {
+    constructor(message: string);
+}
+/** The validated frontmatter plus the markdown body that followed it. */
+export interface ParsedSkill {
+    frontmatter: SkillFrontmatter;
+    body: string;
+}
+/**
+ * Parse and validate a SKILL.md.
+ *
+ * The frontmatter is a deliberately small, strict subset of YAML — `key: value`
+ * scalars, optional surrounding quotes, `#` comment lines — which is all the
+ * two-field schema needs. Anything outside that subset (block scalars, nested
+ * maps, a line without a colon, a missing/unterminated block) is a loud error
+ * rather than a best-effort guess, so a skill never loads with a
+ * silently-misread description.
+ *
+ * @param text the raw file contents
+ * @param dirName the skill directory's basename; `name` must equal it
+ * @throws {SkillValidationError} on any malformed or invalid input
+ */
+export declare function parseSkill(text: string, dirName: string): ParsedSkill;

package/dist/skills/parser.js

@@ -0,0 +1,98 @@
+import { CruxyError, ErrorCode } from "../errors/index.js";
+import { SkillFrontmatterSchema } from "./types.js";
+/**
+ * Thrown when a SKILL.md is malformed or fails validation. A {@link CruxyError}
+ * (code CRUXY_E_SKILL_INVALID) so it carries a stable code if it reaches the
+ * boundary; the loader still catches it to record a `SkillError` and exclude the
+ * skill — loud, never silently skipped.
+ */
+export class SkillValidationError extends CruxyError {
+    constructor(message) {
+        super({
+            code: ErrorCode.SkillInvalid,
+            title: message,
+            nextSteps: [
+                "see the built-in `using-skills` skill for the SKILL.md rules",
+            ],
+        });
+        this.name = "SkillValidationError";
+    }
+}
+// Opening `---` line, frontmatter content (non-greedy), closing `---` line, body.
+const FRONTMATTER_RE = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n([\s\S]*))?$/;
+/**
+ * Parse and validate a SKILL.md.
+ *
+ * The frontmatter is a deliberately small, strict subset of YAML — `key: value`
+ * scalars, optional surrounding quotes, `#` comment lines — which is all the
+ * two-field schema needs. Anything outside that subset (block scalars, nested
+ * maps, a line without a colon, a missing/unterminated block) is a loud error
+ * rather than a best-effort guess, so a skill never loads with a
+ * silently-misread description.
+ *
+ * @param text the raw file contents
+ * @param dirName the skill directory's basename; `name` must equal it
+ * @throws {SkillValidationError} on any malformed or invalid input
+ */
+export function parseSkill(text, dirName) {
+    if (!/^---[ \t]*\r?\n/.test(text)) {
+        throw new SkillValidationError("SKILL.md must begin with a YAML frontmatter block delimited by '---'");
+    }
+    const match = FRONTMATTER_RE.exec(text);
+    if (!match) {
+        throw new SkillValidationError("frontmatter block is not terminated by a closing '---' line");
+    }
+    const raw = parseFrontmatterBlock(match[1]);
+    const body = match[2] ?? "";
+    const result = SkillFrontmatterSchema.safeParse(raw);
+    if (!result.success) {
+        throw new SkillValidationError(`invalid frontmatter: ${formatZodError(result.error)}`);
+    }
+    const frontmatter = result.data;
+    if (frontmatter.name !== dirName) {
+        throw new SkillValidationError(`frontmatter name "${frontmatter.name}" must match the skill directory name "${dirName}"`);
+    }
+    return { frontmatter, body };
+}
+/** Parse the frontmatter block into a flat string map, strictly. */
+function parseFrontmatterBlock(block) {
+    const out = {};
+    for (const rawLine of block.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line === "" || line.startsWith("#"))
+            continue;
+        const colon = line.indexOf(":");
+        if (colon === -1) {
+            throw new SkillValidationError(`invalid frontmatter line (expected "key: value"): ${JSON.stringify(rawLine)}`);
+        }
+        const key = line.slice(0, colon).trim();
+        if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(key)) {
+            throw new SkillValidationError(`invalid frontmatter key: ${JSON.stringify(key)}`);
+        }
+        if (key in out) {
+            throw new SkillValidationError(`duplicate frontmatter key: ${JSON.stringify(key)}`);
+        }
+        out[key] = stripQuotes(line.slice(colon + 1).trim());
+    }
+    return out;
+}
+/** Strip a single pair of matching surrounding quotes, if present. */
+function stripQuotes(value) {
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if ((first === '"' || first === "'") && first === last) {
+            return value.slice(1, -1);
+        }
+    }
+    return value;
+}
+/** Render a zod error to a compact, single-line reason. */
+function formatZodError(error) {
+    return error.issues
+        .map((issue) => {
+        const path = issue.path.join(".");
+        return path ? `${path}: ${issue.message}` : issue.message;
+    })
+        .join("; ");
+}

package/dist/skills/service.d.ts

@@ -0,0 +1,41 @@
+import { type LoaderSources } from "./loader.js";
+import { type Skill, type SkillCatalogEntry, type SkillStatus } from "./types.js";
+/** Logger surface the service reports through. */
+interface SkillServiceLogger {
+    debug(message: string): void;
+}
+/**
+ * A ready-to-use skills catalog for one project root. It resolves the three
+ * sources, caches the catalog, and refreshes lazily when a source directory's
+ * mtime changes (i.e. a skill was added or removed). Bodies are never cached —
+ * {@link SkillService.load} re-reads them on demand, so body edits are always
+ * live. Build one with {@link getSkillService}, which caches per cwd.
+ */
+export interface SkillService {
+    /** Catalog entries (name + description + source), refreshed if stale. */
+    list(): Promise<SkillCatalogEntry[]>;
+    /** Load one skill's body + resolved asset paths. Throws if unknown. */
+    load(name: string): Promise<Skill>;
+    /** Snapshot for `cruxy skills --status`: entries, errors, and source dirs. */
+    status(): Promise<SkillStatus>;
+}
+/**
+ * Explicit dependency overrides for tests — the only way to point the loader at
+ * fixture directories. Production callers never pass this, so they always use
+ * the real project/user/builtin sources.
+ */
+export interface SkillServiceDeps {
+    sources?: Partial<LoaderSources>;
+}
+/** The default source directories for a project root. */
+export declare function defaultSources(cwd: string): LoaderSources;
+/**
+ * Get (or build) the {@link SkillService} for a project root, cached per
+ * resolved cwd. Construction is cheap (just path resolution); the catalog is
+ * built lazily on first use and refreshed on source-mtime change. `deps` is for
+ * explicit test injection only (see {@link SkillServiceDeps}).
+ */
+export declare function getSkillService(cwd: string, logger: SkillServiceLogger, deps?: SkillServiceDeps): SkillService;
+/** Drop all cached services. For tests and process teardown. */
+export declare function resetSkillServices(): void;
+export {};

package/dist/skills/service.js

@@ -0,0 +1,92 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { globalDir } from "../config/index.js";
+import { BUILTIN_SKILLS_DIR, GLOBAL_DIR_NAME, SKILLS_DIR_NAME, } from "../constants.js";
+import { getSkill, loadCatalog } from "./loader.js";
+import { SOURCE_PRECEDENCE, } from "./types.js";
+/** The default source directories for a project root. */
+export function defaultSources(cwd) {
+    const root = path.resolve(cwd);
+    return {
+        project: path.join(root, GLOBAL_DIR_NAME, SKILLS_DIR_NAME),
+        user: path.join(globalDir(), SKILLS_DIR_NAME),
+        builtin: BUILTIN_SKILLS_DIR,
+    };
+}
+class SkillServiceImpl {
+    sources;
+    logger;
+    catalog = null;
+    signature = "";
+    constructor(sources, logger) {
+        this.sources = sources;
+        this.logger = logger;
+    }
+    async ensureFresh() {
+        const signature = await computeSignature(this.sources);
+        if (this.catalog === null || signature !== this.signature) {
+            this.logger.debug("(re)building skill catalog");
+            this.catalog = await loadCatalog(this.sources);
+            this.signature = signature;
+        }
+        return this.catalog;
+    }
+    async list() {
+        return (await this.ensureFresh()).entries;
+    }
+    async load(name) {
+        return getSkill(await this.ensureFresh(), name);
+    }
+    async status() {
+        const catalog = await this.ensureFresh();
+        return {
+            entries: catalog.entries,
+            errors: catalog.errors,
+            sources: SOURCE_PRECEDENCE.map((source) => ({
+                source,
+                dir: this.sources[source],
+            })),
+        };
+    }
+}
+// ── per-cwd cache ─────────────────────────────────────────────────────────────
+const cache = new Map();
+/**
+ * Get (or build) the {@link SkillService} for a project root, cached per
+ * resolved cwd. Construction is cheap (just path resolution); the catalog is
+ * built lazily on first use and refreshed on source-mtime change. `deps` is for
+ * explicit test injection only (see {@link SkillServiceDeps}).
+ */
+export function getSkillService(cwd, logger, deps) {
+    const root = path.resolve(cwd);
+    let service = cache.get(root);
+    if (!service) {
+        const sources = { ...defaultSources(root), ...(deps?.sources ?? {}) };
+        service = new SkillServiceImpl(sources, logger);
+        cache.set(root, service);
+    }
+    return service;
+}
+/** Drop all cached services. For tests and process teardown. */
+export function resetSkillServices() {
+    cache.clear();
+}
+/**
+ * A cheap change signature: the mtime of each source directory. A directory's
+ * mtime changes when an entry is added or removed, so this catches new/deleted
+ * skills. (Editing a body in place doesn't change it — but `load` always
+ * re-reads bodies fresh, so only the cached catalog's name/description can lag.)
+ */
+async function computeSignature(sources) {
+    const parts = [];
+    for (const source of SOURCE_PRECEDENCE) {
+        try {
+            const stat = await fs.stat(sources[source]);
+            parts.push(`${source}:${stat.mtimeMs}`);
+        }
+        catch {
+            parts.push(`${source}:absent`);
+        }
+    }
+    return parts.join("|");
+}

package/dist/skills/types.d.ts

@@ -0,0 +1,94 @@
+import { z } from "zod";
+/**
+ * Shared types for the skills system (C.18). A *skill* is a directory holding a
+ * `SKILL.md` — YAML frontmatter (name + description) plus a markdown
+ * instructions body — and optional `scripts/` and `reference/` asset subdirs.
+ *
+ * Progressive disclosure is the whole point: only `name` + `description` enter
+ * the agent's context by default (the catalog); the full body is read on demand
+ * by `load_skill`. Bodies are never held in the cached catalog.
+ */
+/** Where a skill was discovered, highest precedence first. */
+export type SkillSource = "project" | "user" | "builtin";
+/** Precedence order: project overrides user overrides builtin. */
+export declare const SOURCE_PRECEDENCE: readonly SkillSource[];
+/**
+ * Strict schema for SKILL.md frontmatter. `.strict()` rejects unknown keys, so a
+ * typo'd field is a loud error rather than silently ignored. `name` is
+ * kebab-case and must equal the skill's directory name (enforced by the parser).
+ */
+export declare const SkillFrontmatterSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    description: string;
+}, {
+    name: string;
+    description: string;
+}>;
+export type SkillFrontmatter = z.infer<typeof SkillFrontmatterSchema>;
+/**
+ * The cheap catalog entry the agent sees by default — name, one-line
+ * description, and which source won. No body.
+ */
+export interface SkillCatalogEntry {
+    name: string;
+    description: string;
+    source: SkillSource;
+}
+/**
+ * A fully-loaded skill, returned by `load_skill`/`getSkill`. Carries the
+ * markdown body plus resolved, in-bounds asset paths.
+ */
+export interface Skill {
+    name: string;
+    description: string;
+    source: SkillSource;
+    /** Markdown instructions (everything after the frontmatter block). */
+    body: string;
+    /** Absolute path of the skill directory — the root for its assets. */
+    assetRoot: string;
+    /** Project-relative-to-assetRoot POSIX paths of files under `scripts/`. */
+    scripts: string[];
+    /** Project-relative-to-assetRoot POSIX paths of files under `reference/`. */
+    references: string[];
+}
+/**
+ * A validation failure for one candidate skill. Collected (never thrown past the
+ * loader) so one bad skill can't break the catalog; surfaced loudly in
+ * `cruxy skills --status` and excluded from the catalog.
+ */
+export interface SkillError {
+    source: SkillSource;
+    /** Absolute path of the offending skill directory. */
+    dir: string;
+    /** The directory's basename (the would-be skill name), for display. */
+    name: string;
+    /** Actionable, human-readable reason. */
+    message: string;
+}
+/**
+ * The resolved catalog: valid entries (deduped by precedence), the validation
+ * errors that were excluded, and a name→location index used by `getSkill` to
+ * read a body on demand. Bodies are intentionally absent.
+ */
+export interface SkillCatalog {
+    entries: SkillCatalogEntry[];
+    errors: SkillError[];
+    /** name → winning skill's directory + source (for on-demand body reads). */
+    byName: Map<string, {
+        dir: string;
+        source: SkillSource;
+    }>;
+}
+/** Snapshot for `cruxy skills --status`. */
+export interface SkillStatus {
+    entries: SkillCatalogEntry[];
+    errors: SkillError[];
+    /** The three source directories, in precedence order. */
+    sources: {
+        source: SkillSource;
+        dir: string;
+    }[];
+}

package/dist/skills/types.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+/** Precedence order: project overrides user overrides builtin. */
+export const SOURCE_PRECEDENCE = [
+    "project",
+    "user",
+    "builtin",
+];
+/**
+ * Strict schema for SKILL.md frontmatter. `.strict()` rejects unknown keys, so a
+ * typo'd field is a loud error rather than silently ignored. `name` is
+ * kebab-case and must equal the skill's directory name (enforced by the parser).
+ */
+export const SkillFrontmatterSchema = z
+    .object({
+    name: z
+        .string()
+        .min(1)
+        .regex(/^[a-z0-9][a-z0-9-]*$/, "must be kebab-case: lowercase letters, digits, and hyphens, starting with a letter or digit"),
+    description: z.string().min(1),
+})
+    .strict();

package/dist/tools/file/paths.d.ts

@@ -1,10 +1,12 @@
+import { CruxyError } from "../../errors/index.js";
 import type { ToolContext } from "../types.js";
 /**
  * Thrown when a tool argument resolves to a path outside the project root —
  * whether via `../` traversal, an absolute path, or a symlink pointing outward.
- * Tools catch this and surface it as `{ ok:false }` rather than letting it throw.
+ * A {@link CruxyError} (code CRUXY_E_PATH_ESCAPE) so it carries a code if it
+ * reaches the boundary; tools still catch it and surface `{ ok:false }`.
  */
-export declare class PathEscapeError extends Error {
+export declare class PathEscapeError extends CruxyError {
     constructor(message: string);
 }
 /**

package/dist/tools/file/paths.js

@@ -1,13 +1,15 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
+import { CruxyError, ErrorCode } from "../../errors/index.js";
 /**
  * Thrown when a tool argument resolves to a path outside the project root —
  * whether via `../` traversal, an absolute path, or a symlink pointing outward.
- * Tools catch this and surface it as `{ ok:false }` rather than letting it throw.
+ * A {@link CruxyError} (code CRUXY_E_PATH_ESCAPE) so it carries a code if it
+ * reaches the boundary; tools still catch it and surface `{ ok:false }`.
  */
-export class PathEscapeError extends Error {
+export class PathEscapeError extends CruxyError {
     constructor(message) {
-        super(message);
+        super({ code: ErrorCode.PathEscape, title: message });
         this.name = "PathEscapeError";
     }
 }

package/dist/tools/index.d.ts

@@ -3,4 +3,6 @@ export * from "./registry.js";
 export * from "./list-files.js";
 export * from "./git-status.js";
 export * from "./search-codebase.js";
+export * from "./list-skills.js";
+export * from "./load-skill.js";
 export * from "./file/index.js";

package/dist/tools/index.js

@@ -3,4 +3,6 @@ export * from "./registry.js";
 export * from "./list-files.js";
 export * from "./git-status.js";
 export * from "./search-codebase.js";
+export * from "./list-skills.js";
+export * from "./load-skill.js";
 export * from "./file/index.js";

package/dist/tools/list-skills.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+import type { Tool } from "./types.js";
+/**
+ * List the available skills (name + one-line description + source). Read-only —
+ * no approval — like the other discovery tools. This is the cheap half of
+ * progressive disclosure: only the catalog enters context here; the agent calls
+ * `load_skill` to pull a skill's full instructions when a task matches.
+ */
+export declare const listSkillsTool: Tool<z.ZodObject<Record<string, never>>>;

package/dist/tools/list-skills.js

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { getSkillService } from "../skills/index.js";
+/**
+ * List the available skills (name + one-line description + source). Read-only —
+ * no approval — like the other discovery tools. This is the cheap half of
+ * progressive disclosure: only the catalog enters context here; the agent calls
+ * `load_skill` to pull a skill's full instructions when a task matches.
+ */
+export const listSkillsTool = {
+    name: "list_skills",
+    description: "List the specialized skills available for this project (name, description, and source: project/user/builtin). Call this when a task might match a skill; then call load_skill to load the one that fits. Read-only and requires no approval.",
+    parameters: z.object({}),
+    async execute(_input, ctx) {
+        try {
+            const entries = await getSkillService(ctx.cwd, ctx.logger).list();
+            if (entries.length === 0) {
+                return {
+                    ok: true,
+                    output: "(no skills available — add one under .cruxy/skills/ or ~/.cruxy/skills/)",
+                };
+            }
+            return { ok: true, output: formatCatalog(entries) };
+        }
+        catch (err) {
+            return { ok: false, error: err.message };
+        }
+    },
+};
+/** Render the catalog as a compact, model-readable list. */
+function formatCatalog(entries) {
+    return entries
+        .map((e) => `- ${e.name} [${e.source}] — ${e.description}`)
+        .join("\n");
+}

package/dist/tools/load-skill.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import type { Tool } from "./types.js";
+declare const parameters: z.ZodObject<{
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+}, {
+    name: string;
+}>;
+/**
+ * Load a skill's full instructions on demand — the expensive half of
+ * progressive disclosure. Returns the markdown body plus the absolute asset root
+ * and the relative paths of any `scripts/` and `reference/` files, so the agent
+ * can read or run them through the existing read_file / run_command tools.
+ *
+ * Read-only — no approval. Loading a skill never executes anything: scripts are
+ * surfaced as paths only and run, if at all, through run_command (which applies
+ * the normal approval gate).
+ */
+export declare const loadSkillTool: Tool<typeof parameters>;
+export {};

package/dist/tools/load-skill.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { getSkillService } from "../skills/index.js";
+const parameters = z.object({
+    name: z
+        .string()
+        .min(1)
+        .describe("The exact name of the skill to load (from list_skills)."),
+});
+/**
+ * Load a skill's full instructions on demand — the expensive half of
+ * progressive disclosure. Returns the markdown body plus the absolute asset root
+ * and the relative paths of any `scripts/` and `reference/` files, so the agent
+ * can read or run them through the existing read_file / run_command tools.
+ *
+ * Read-only — no approval. Loading a skill never executes anything: scripts are
+ * surfaced as paths only and run, if at all, through run_command (which applies
+ * the normal approval gate).
+ */
+export const loadSkillTool = {
+    name: "load_skill",
+    description: "Load the full instructions for a skill by name (discover names with list_skills). Returns the skill's markdown body plus the paths of any bundled scripts/reference files. Read-only and requires no approval — it never runs anything; use run_command to execute a script the skill describes.",
+    parameters,
+    async execute(input, ctx) {
+        try {
+            const skill = await getSkillService(ctx.cwd, ctx.logger).load(input.name);
+            return { ok: true, output: formatSkill(skill) };
+        }
+        catch (err) {
+            return { ok: false, error: err.message };
+        }
+    },
+};
+/** Render a loaded skill: instructions, then an asset reference footer. */
+function formatSkill(skill) {
+    const parts = [
+        `# Skill: ${skill.name} (${skill.source})`,
+        "",
+        skill.body.trim(),
+    ];
+    const footer = [`Asset root: ${skill.assetRoot}`];
+    if (skill.scripts.length > 0) {
+        footer.push(`Scripts (run via run_command — not auto-executed): ${skill.scripts.join(", ")}`);
+    }
+    if (skill.references.length > 0) {
+        footer.push(`References (read via read_file): ${skill.references.join(", ")}`);
+    }
+    parts.push("", "---", footer.join("\n"));
+    return parts.join("\n");
+}

package/dist/tools/registry.js

@@ -4,6 +4,8 @@ import { gitStatusTool } from "./git-status.js";
 import { readFileTool, writeFileTool, editFileTool, applyPatchTool, globTool, grepFilesTool, } from "./file/index.js";
 import { runCommandTool } from "./shell/index.js";
 import { searchCodebaseTool } from "./search-codebase.js";
+import { listSkillsTool } from "./list-skills.js";
+import { loadSkillTool } from "./load-skill.js";
 /**
  * In-memory catalogue of the tools available to the agent. Names are unique;
  * `toToolSpecs()` projects the catalogue into the `@cruxy/sdk` wire format.
@@ -61,5 +63,7 @@ export function buildDefaultRegistry() {
     registry.register(gitStatusTool);
     registry.register(runCommandTool);
     registry.register(searchCodebaseTool);
+    registry.register(listSkillsTool);
+    registry.register(loadSkillTool);
     return registry;
 }

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@cruxy/cli",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {
     "cruxy": "./dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "engines": {
     "node": ">=20"

package/skills/git-commit/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: git-commit
+description: Write a conventional commit message that passes this repo's commitlint. Use when committing, writing a commit message, or opening a PR in cruxy.
+---
+
+# Writing commit messages for cruxy
+
+This repo enforces [Conventional Commits](https://www.conventionalcommits.org)
+via commitlint (a husky `commit-msg` hook) plus changesets. Follow this to get a
+message that passes on the first try.
+
+## Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+- **type** — one of `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `perf`,
+  `build`, `ci`, `style`, `revert`.
+- **scope** _(optional, but if present must be in the allow-list)_ —
+  `cli`, `sdk`, `ui`, `api`, `auth`, `billing`, `web`, `dashboard`, `docs`,
+  `ide`, `infra`, `pricing`, `repo`, `ci`. The canonical list lives in
+  `commitlint.config.cjs` (`scope-enum`).
+- **subject** — imperative mood, no trailing period.
+
+## The rule people trip on
+
+**The subject must NOT start with a capital letter.** commitlint's
+`subject-case` rejects sentence-case / start-case / pascal-case / upper-case, so
+a subject beginning with an uppercase letter fails the hook (and CI). A tag like
+`C.18` cannot be the first token.
+
+- ✅ `feat(cli): codebase indexing + search_codebase (C.18)`
+- ❌ `feat(cli): C.18 codebase indexing` — capital `C` ⇒ sentence-case ⇒ rejected.
+
+Put any phase/issue tag in a parenthetical at the end, or lowercase the lead.
+
+## Body and footer
+
+- Wrap the body at ~72 columns; explain _what_ and _why_, not _how_.
+- A breaking change uses `!` after the type/scope (`feat(cli)!: …`) and/or a
+  `BREAKING CHANGE:` footer.
+- Co-author trailers go in the footer, e.g.
+  `Co-Authored-By: Name <email>`.
+
+## Don't forget the changeset
+
+User-facing changes need a changeset: run `pnpm changeset` (or add a file under
+`.changeset/`) describing the change and the semver bump for the affected
+package (e.g. `@cruxy/cli` minor).
+
+## Quick check
+
+If a commit is rejected with `subject must not be sentence-case … [subject-case]`,
+lowercase the first word of the subject (or move the capitalized tag into a
+trailing parenthetical) and recommit.