trunative 1.0.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,142 @@
+# Trunative
+
+A mobile-only design skill for AI coding agents.
+
+![skills.sh](https://skills.sh/b/TiagoDanin/Trunative)
+
+Trunative is a [skill](https://www.skills.sh/docs) that makes coding agents treat mobile as its own platform rather than a narrow browser window. A phone is not a small desktop: input is imprecise and one-handed, the session gets interrupted by calls and notifications, the network drops mid-request, the OS owns gestures and insets and permissions, text scales to whatever the user set, the battery and the thermal budget are finite, and the whole thing is often used outdoors while walking. Those constraints, not the viewport width, are what a mobile design has to answer for.
+
+It is stack-agnostic: the rules apply to React Native, Expo, Flutter, SwiftUI, Jetpack Compose, or mobile web, and the agent detects the framework and translates.
+
+## Why
+
+Coding agents are trained mostly on desktop web. Left alone, they produce mobile screens that are technically correct and physically unusable:
+
+- A tap target that measures 32 points because that is what the icon measures, and misses under a thumb that is not looking at it (`touch-floor`).
+- The primary action parked at the top of the screen, in the part of it a hand cannot reach without regripping the phone (`touch-reach`).
+- Insets taken from a constant instead of from the framework, so the last row of the list sits under the home indicator on the one device nobody opened (`layout-insets`).
+- One design for the case where the data arrived: no shape to load into, no sentence for the empty list, and a failure that does not say what failed (`state-set`).
+- A layout that holds at the default text size and falls apart two steps up the accessibility scale, which is where a lot of people already are (`type-scaling`).
+- A dark theme that is the light one with its colours inverted, so what was a shadow is now a glow (`color-dark-composed`).
+- Seed data chosen to flatter the layout: three short names, no zero, no null, no long string, no empty list (`copy-sample-data`).
+- A hero image filling a third of the screen and depicting nothing anybody chose (`icon-depicts`).
+
+None of this shows up in a code review or a passing test suite. It shows up when someone holds the phone.
+
+Trunative encodes the constraints that mobile actually imposes, such as reach, touch precision, interruption, latency, sunlight and one hand, as rules the agent applies before writing the first component, and as a checklist it verifies against afterwards. Desktop is explicitly out of scope: there is no responsive breakpoint to hide behind, so no decision gets deferred to "it'll be fine on a big screen".
+
+## Installation
+
+```sh
+npx trunative install
+```
+
+This copies the skill into every agent directory the project already has (`.claude`, `.agents`, `.antigravity`, `.codex`, `.opencode`), and writes `.trunative/skill.lock` so the agent can tell when its copy is out of date.
+
+Then, before the agent starts:
+
+```sh
+npx trunative doctor
+```
+
+It checks that the project has its three briefs, in `.trunative/` or at the root, and that the installed skill matches the current version:
+
+- `PRODUCT.md`, who uses the app and what it is for.
+- `DESIGN.md`, the visual identity, in the [design.md format](https://github.com/google-labs-code/design.md) from Google Labs.
+- `STACK.md`, the codebase itself: UI primitives, navigation, components, accepted exceptions.
+
+The doctor reports and exits 1, it never writes the briefs. Writing them is the agent's job in the init step.
+
+A fourth brief is per screen instead of per project. The agent writes one to `.trunative/screens/<name>.md` whenever a task changes hierarchy, actions, states or navigation, and this checks it:
+
+```sh
+npx trunative spec
+```
+
+The agent also has a generator for the review checklist:
+
+```sh
+npx trunative rubric --only touch --only forms
+```
+
+It prints one row per rule id, with that rule's own checklist line as the criterion, so the checklist comes out of the heuristics instead of being written by hand. A rule added today shows up in the next review with no second edit.
+
+The skills.sh CLI works too, without the lockfile and the version check:
+
+```sh
+npx skills add TiagoDanin/Trunative --skill trunative
+```
+
+The repository carries seven copies: `trunative` covers every stack, and `trunative-flutter`, `trunative-expo`, `trunative-react-native`, `trunative-swiftui`, `trunative-compose` and `trunative-web` are the same skill with the other frameworks' instructions removed. Pick one with `--skill`, or list them with `-l`. `npx trunative install` needs none of this: it reads the stack from `STACK.md` and resolves the copy itself.
+
+To install manually, copy one of those folders into your agent's skills directory:
+
+```sh
+git clone https://github.com/TiagoDanin/Trunative.git
+cp -r Trunative/skills/trunative .claude/skills/trunative
+```
+
+## Usage
+
+The skill loads on its own when the task is mobile UI work. Building a screen, a component, a navigation flow, a form, or reviewing an existing one. No command needed:
+
+```
+Build the checkout screen for the app.
+Add a filter sheet to the product list.
+Review this screen does it work one-handed?
+```
+
+To force it, name it:
+
+```
+Use the trunative skill on src/screens/Checkout.tsx
+```
+
+The agent then:
+
+1. **Detects the stack** and maps the rules to that framework's primitives (`SafeAreaView`, `SafeArea`, `WindowInsets`, `env(safe-area-inset-*)`, …).
+2. **Settles the structure first**, when the task moves hierarchy, actions, states or navigation. It writes a screen brief to `.trunative/screens/`, draws it as a greyscale wireframe, and asks once before any code exists. Approving a picture costs a fraction of rewriting a screen, and a cosmetic change skips this entirely.
+3. **Applies the design principles** below while writing the code.
+4. **Audits the result** against the checklist and reports what it could not satisfy, instead of silently shipping it.
+
+That audit scores every rule that applies from 1 to 5, and a 1 or a 2 sends the agent back to fix it before the work is handed over.
+
+The same review runs heavier on a screen that already exists, asked for by name:
+
+```
+Review the checkout screen
+```
+
+It drives the app instead of reading the diff, separates what was read in the source from what was seen on a device, writes the result into `.trunative/review/`, and prints the score against the last run's.
+
+## Design Principles
+
+The rules the skill enforces. Each is a hard constraint, not a preference, and each carries a stable id the agent reports against. `src/skills/heuristics/` is the source of truth; this is the summary.
+
+Ten files open on every screen, because every screen has colour, text, targets, a layout, states, at least one action, words, something that moves and something drawn.
+
+**Colour** is reached through a role, never as a hex at a call site (`color-roles`). One accent means touchable and nothing else (`color-one-accent`). Dark is a second design rather than an inverted switch (`color-dark-composed`), contrast is calculated rather than eyeballed (`color-contrast`), and nothing is said by colour alone (`color-not-alone`).
+
+**Type** comes from the platform ramp, so no component carries a literal size (`type-scale`), and the screen is rendered at the largest accessibility step before anyone calls it done (`type-scaling`). Body copy stays at a readable measure (`type-measure`) and the longest translation still fits (`type-strings`).
+
+**Touch** is the one every desktop habit breaks. The target is the hit area and not the drawing, at 44pt or 48dp (`touch-floor`), with 8dp of dead space between neighbours (`touch-spacing`). The bottom third is the only easy part of the screen (`touch-reach`), destructive actions sit away from it (`touch-destructive`), every press answers within about 100ms outside the area the finger covers (`touch-feedback`), and the screen edges belong to the operating system (`touch-gestures`).
+
+**Buttons** allow exactly one primary action per screen (`button-one-primary`), with emphasis taken from the platform's own ladder (`button-ladder`) and labels that name what will happen (`button-label`).
+
+**Layout** takes its insets from the framework at runtime rather than from a constant (`layout-insets`), keeps one column and one scrolling axis (`layout-column`), and survives the narrow device (`layout-width`). The first screenful answers what the screen is and what to do (`layout-fold`).
+
+**States** are named before the happy path is written, all six of them (`state-set`). Loading is a placeholder shaped like the content (`state-loading`), the three empties get three different sentences (`state-empty`), errors say what failed without inventing why (`state-error`), offline is four states rather than a boolean (`state-offline`), and work in progress survives the system killing the process (`state-interrupt`).
+
+**Motion** earns its place by answering continuity, latency or acknowledgement (`motion-job`), leaves the platform's own transitions alone (`motion-platform`), never holds the user still (`motion-blocks`), and reads the reduced-motion setting on every platform it ships to (`motion-reduced`).
+
+**Accessibility** gives every control a name, a role and a value (`a11y-name`), hides decoration rather than describing it (`a11y-hidden`), and never makes a gesture the only route to anything (`a11y-gesture`). One whole flow is driven with the screen reader on before it ships (`a11y-test`).
+
+**Copy** decides its word budget before the sentence is written (`copy-budget`), spends the first two words on meaning (`copy-first-word`), names the failure and ends on the fix (`copy-error`), and uses one term per thing throughout (`copy-terms`). Sample content is chosen to break the layout rather than to flatter it (`copy-sample-data`).
+
+**Icons and imagery** come from one set, at one weight, and an emoji is not a substitute for a missing icon (`icon-one-set`, `icon-no-emoji`). Artwork depicts something somebody chose, and decoration that means nothing loses its space to content (`icon-depicts`). The space an image will occupy is reserved before it lands, so nothing jumps under a thumb already moving (`icon-reserve`), and anything drawn light on dark needs its own variant rather than a filter (`icon-dark`).
+
+The rest of the rules open when the screen touches them: navigation and back (`nav-`), lists (`list-`), forms (`form-`), chat (`chat-`), permissions (`perm-`), onboarding (`onboard-`), localization (`l10n-`), notifications (`notify-`), widgets and live surfaces (`widget-`), device capabilities (`sense-`), camera (`cam-`), network (`net-`), offline (`off-`), the launch surface (`splash-`), performance (`perf-`), feedback (`fb-`), search (`search-`), auth (`auth-`), settings (`set-`), media (`media-`), background work (`bg-`), privacy (`priv-`), sharing (`share-`), updates and migrations (`upd-`), scrolling (`scroll-`), data and charts (`data-`), sound (`sound-`), payments (`pay-`), ads (`ads-`), maps (`map-`) and web views (`webview-`).
+
+## License
+
+[MIT](LICENSE) © Tiago Danin

package/dist/cli.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { build } from './commands/build.js';
+import { detect } from './commands/detect.js';
+import { doctor } from './commands/doctor.js';
+import { graph } from './commands/graph.js';
+import { lint } from './commands/lint.js';
+import { install } from './commands/install.js';
+import { rubric } from './commands/rubric.js';
+import { spec } from './commands/spec.js';
+import { packageRoot } from './paths.js';
+const USAGE = `trunative, a mobile-only design skill for AI coding agents
+
+Usage
+  npx trunative doctor            check the project before the agent starts
+  npx trunative install [--dir]   copy the skill into the agent directories
+  npx trunative spec [paths]      check the screen briefs, exits 1 on a finding
+  npx trunative rubric [--only]   print the review checklist, one row per rule
+  npx trunative build             resolve the skill once per agent and stack
+  npx trunative lint              check the written skill, exits 1 on a finding
+  npx trunative graph [--only]    render the skill's structure
+  npx trunative detect [paths]    answer the Check lines a file can settle
+
+Options
+  --dir <path>   install into this directory instead of the detected ones
+                 (repeatable)
+  --cwd <path>   run against this project instead of the current directory
+  --stack <name> install the copy resolved for this stack, instead of the one
+                 the STACK.md "Stack:" line names
+  --only <name>  limit the rubric to a heuristics file ("touch"), a rule
+                 prefix ("touch-") or one rule id (repeatable)
+  --format <f>   rubric output: markdown (default), json, ids
+  --check        accepted on "spec", which only ever checks
+  -v, --version  print the version
+  -h, --help     print this help
+
+The repository layout stays compatible with skills.sh, so
+"npx skills add TiagoDanin/Trunative" keeps working as an alternative.
+`;
+async function readVersion() {
+    try {
+        const source = await readFile(join(packageRoot, 'package.json'), 'utf8');
+        return JSON.parse(source).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+async function main() {
+    const { values, positionals } = parseArgs({
+        args: process.argv.slice(2),
+        allowPositionals: true,
+        options: {
+            dir: { type: 'string', multiple: true },
+            only: { type: 'string', multiple: true },
+            format: { type: 'string' },
+            stack: { type: 'string' },
+            cwd: { type: 'string' },
+            check: { type: 'boolean' },
+            version: { type: 'boolean', short: 'v' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+    const version = await readVersion();
+    if (values.version) {
+        console.log(version);
+        return 0;
+    }
+    const command = positionals[0];
+    if (values.help || !command || command === 'help') {
+        console.log(USAGE);
+        return command || values.help ? 0 : 1;
+    }
+    const cwd = values.cwd ? join(process.cwd(), values.cwd) : process.cwd();
+    switch (command) {
+        case 'doctor':
+            return doctor({ cwd, version });
+        case 'install':
+            return install({ cwd, version, dirs: values.dir, stack: values.stack });
+        case 'build':
+            return build({ version });
+        case 'lint':
+            return lint({ cwd });
+        case 'spec':
+            return spec({ cwd, paths: positionals.slice(1) });
+        case 'detect':
+            return detect({
+                cwd,
+                paths: positionals.slice(1),
+                only: values.only,
+                format: values.format,
+            });
+        case 'graph':
+            return graph({ only: values.only, format: values.format });
+        case 'rubric':
+            return rubric({ version, only: values.only, format: values.format });
+        default:
+            console.error(`unknown command "${command}"\n`);
+            console.error(USAGE);
+            return 1;
+    }
+}
+process.exitCode = await main();

package/dist/commands/build.js

@@ -0,0 +1,35 @@
+import { rm } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { AGENTS, STACKS } from '../compile.js';
+import { readSources, resolve, write } from '../emit.js';
+import { AGENT_DIR, compiledSkillsDir, PUBLISHED_AGENT, publishedSkillsDir, variantName, } from '../paths.js';
+export async function build(options) {
+    const sources = await readSources();
+    const variants = [undefined, ...STACKS];
+    let written = 0;
+    for (const agent of AGENTS) {
+        for (const stack of variants) {
+            const target = stack ? { agent, stack } : { agent };
+            const destination = join(compiledSkillsDir, AGENT_DIR[agent] ?? `.${agent}`, 'skills', variantName('trunative', stack));
+            written += await write(resolve(sources, target), destination);
+        }
+    }
+    // The published copies. A stale variant would keep being served, so the
+    // directory is emptied rather than written over.
+    await rm(publishedSkillsDir, { recursive: true, force: true });
+    let published = 0;
+    for (const stack of variants) {
+        const target = stack ? { agent: PUBLISHED_AGENT, stack } : { agent: PUBLISHED_AGENT };
+        const destination = join(publishedSkillsDir, variantName('trunative', stack));
+        published += await write(resolve(sources, target), destination);
+    }
+    const names = variants.map((stack) => variantName('trunative', stack)).join(', ');
+    const dirs = AGENTS.map((agent) => AGENT_DIR[agent] ?? `.${agent}`).join(', ');
+    const at = (path) => relative(process.cwd(), path).split(sep).join('/');
+    console.log(`built ${written} files for trunative ${options.version}`);
+    console.log(`directories: ${dirs}`);
+    console.log(`skills in each: ${names}`);
+    console.log(`into ${at(compiledSkillsDir)}`);
+    console.log(`published ${published} files into ${at(publishedSkillsDir)} (${names}, resolved for ${PUBLISHED_AGENT})`);
+    return 0;
+}

package/dist/commands/detect.js

@@ -0,0 +1,91 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { extname, join, relative, sep } from 'node:path';
+import { DETECTORS } from '../detect/rules.js';
+/** Directories a scan never enters, because nothing in them is the app. */
+const SKIPPED = new Set([
+    'node_modules',
+    'build',
+    'dist',
+    '.dart_tool',
+    'Pods',
+    '.git',
+    '.gradle',
+    'DerivedData',
+    'ios/Flutter',
+]);
+const EXTENSIONS = new Set(DETECTORS.flatMap((detector) => detector.extensions));
+async function walk(root, dir, found) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (SKIPPED.has(entry.name)) {
+            continue;
+        }
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            await walk(root, full, found);
+        }
+        else if (entry.isFile() && EXTENSIONS.has(extname(entry.name).toLowerCase())) {
+            found.push(relative(root, full).split(sep).join('/'));
+        }
+    }
+}
+/** Files the detectors can read, under the paths asked for. */
+async function scannable(cwd, paths) {
+    const found = [];
+    for (const path of paths.length > 0 ? paths : ['.']) {
+        const full = join(cwd, path);
+        const info = await stat(full).catch(() => null);
+        if (!info) {
+            continue;
+        }
+        if (info.isDirectory()) {
+            await walk(cwd, full, found);
+        }
+        else if (EXTENSIONS.has(extname(full).toLowerCase())) {
+            found.push(relative(cwd, full).split(sep).join('/'));
+        }
+    }
+    return found.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+export async function detect(options) {
+    const { cwd } = options;
+    const only = options.only ?? [];
+    const detectors = DETECTORS.filter((detector) => only.length === 0 || only.some((term) => detector.rule === term || detector.rule.startsWith(term)));
+    if (detectors.length === 0) {
+        console.error(`no detector matches --only ${only.join(', ')}`);
+        console.error(`detectors: ${DETECTORS.map((detector) => detector.rule).join(', ')}`);
+        return 1;
+    }
+    const files = await scannable(cwd, options.paths ?? []);
+    const findings = [];
+    for (const file of files) {
+        const source = await readFile(join(cwd, ...file.split('/')), 'utf8');
+        const extension = extname(file).toLowerCase();
+        for (const detector of detectors) {
+            if (detector.extensions.includes(extension)) {
+                findings.push(...detector.run(file, source));
+            }
+        }
+    }
+    findings.sort((a, b) => (a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1));
+    if (options.format === 'json') {
+        console.log(JSON.stringify({
+            scanned: files.length,
+            rules: detectors.map((detector) => detector.rule),
+            findings,
+        }, undefined, '\t'));
+        return findings.length > 0 ? 2 : 0;
+    }
+    for (const found of findings) {
+        console.log(`${found.file}:${found.line}  ${found.rule}  ${found.message}`);
+    }
+    console.log(`\n${findings.length} finding(s) in ${files.length} file(s), from ${detectors.length} detector(s).`);
+    console.log('Source evidence only: a finding is a place to look, and silence is not a pass.');
+    return findings.length > 0 ? 2 : 0;
+}

package/dist/commands/doctor.js

@@ -0,0 +1,110 @@
+import { stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { readSources, resolve } from '../emit.js';
+import { readLock } from '../lock.js';
+import { briefCandidates, packagedSkillDir } from '../paths.js';
+import { hashFiles, hashSkill, readSkillName } from '../skill.js';
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function checkBrief(cwd, file, label) {
+    for (const candidate of briefCandidates(cwd, file)) {
+        if (await exists(candidate)) {
+            return { name: label, ok: true, detail: relative(cwd, candidate).replace(/\\/g, '/') };
+        }
+    }
+    return {
+        name: label,
+        ok: false,
+        detail: `not found, expected .trunative/${file} or ${file}`,
+    };
+}
+/**
+ * Compares each installed copy against the same variant resolved from the
+ * skill shipping in this package. Every target has its own hash, because a copy
+ * resolved for one agent and one stack is not the same bytes as another.
+ */
+async function checkSkill(cwd, version) {
+    const source = await hashSkill(packagedSkillDir);
+    const name = await readSkillName(packagedSkillDir);
+    const lock = await readLock(cwd);
+    if (!lock) {
+        return [
+            {
+                name: 'skill installed',
+                ok: false,
+                detail: 'no .trunative/skill.lock, run "npx trunative install"',
+            },
+        ];
+    }
+    const checks = [
+        {
+            name: 'skill installed',
+            ok: true,
+            detail: `${lock.skill} in ${lock.targets.map((target) => target.dir).join(', ')}`,
+        },
+    ];
+    const sources = await readSources();
+    const missing = [];
+    const stale = [];
+    for (const target of lock.targets) {
+        const destination = join(cwd, ...target.dir.split('/'));
+        if (!(await exists(destination))) {
+            missing.push(target.dir);
+            continue;
+        }
+        const shape = target.stack
+            ? { agent: target.agent, stack: target.stack }
+            : { agent: target.agent };
+        if ((await hashSkill(destination)) !== hashFiles(resolve(sources, shape))) {
+            stale.push(target.dir);
+        }
+    }
+    if (missing.length > 0) {
+        checks.push({
+            name: 'skill present',
+            ok: false,
+            detail: `missing in ${missing.join(', ')}, run "npx trunative install"`,
+        });
+    }
+    if (stale.length > 0 || lock.hash !== source) {
+        const reason = stale.length > 0
+            ? `content differs in ${stale.join(', ')}`
+            : `installed with trunative@${lock.version}, this is ${version}`;
+        checks.push({
+            name: 'skill up to date',
+            ok: false,
+            detail: `${reason}, run "npx trunative install"`,
+        });
+    }
+    else {
+        checks.push({ name: 'skill up to date', ok: true, detail: `${name} ${source.slice(0, 19)}` });
+    }
+    return checks;
+}
+export async function doctor(options) {
+    const { cwd, version } = options;
+    const checks = [
+        await checkBrief(cwd, 'PRODUCT.md', 'product brief'),
+        await checkBrief(cwd, 'DESIGN.md', 'design brief'),
+        await checkBrief(cwd, 'STACK.md', 'stack brief'),
+        ...(await checkSkill(cwd, version)),
+    ];
+    const width = Math.max(...checks.map((check) => check.name.length));
+    for (const check of checks) {
+        console.log(`${check.ok ? 'PASS' : 'FAIL'}  ${check.name.padEnd(width)}  ${check.detail}`);
+    }
+    const failed = checks.filter((check) => !check.ok);
+    if (failed.length === 0) {
+        console.log('\nReady. Start the build step.');
+        return 0;
+    }
+    console.log(`\n${failed.length} check(s) failed. Fix them before the build step.`);
+    return 1;
+}

package/dist/commands/graph.js

@@ -0,0 +1,106 @@
+import { basename } from 'node:path';
+import { readGraph } from '../graph.js';
+const FORMATS = ['mermaid', 'json', 'text'];
+function id(path) {
+    return path.replace(/[^a-zA-Z0-9]/g, '_');
+}
+/** Heuristic to heuristic, counted, so two files claiming one concern show up. */
+function crossReferences(graph) {
+    const owner = new Map(graph.rules.map((rule) => [rule.id, rule.file]));
+    const edges = new Map();
+    for (const mention of graph.mentions) {
+        if (!mention.file.startsWith('heuristics/')) {
+            continue;
+        }
+        const from = basename(mention.file, '.md');
+        const to = owner.get(mention.id);
+        if (!to || to === from) {
+            continue;
+        }
+        const key = `${from} ${to}`;
+        edges.set(key, (edges.get(key) ?? 0) + 1);
+    }
+    return edges;
+}
+function mermaid(graph, only) {
+    const base = graph.index.base.map((path) => basename(path, '.md'));
+    const lines = ['flowchart LR', '  SKILL["SKILL.md"]'];
+    for (const file of graph.index.flow) {
+        lines.push(`  SKILL --> ${id(file)}["${file}"]`);
+    }
+    for (const heuristic of graph.heuristics) {
+        const tier = base.includes(heuristic.file) ? 'base' : 'extra';
+        const node = id(heuristic.file);
+        if (only.includes(heuristic.file)) {
+            lines.push(`  subgraph ${node}_g["${heuristic.file} (${tier})"]`);
+            for (const rule of heuristic.rules) {
+                const mark = rule.evidence === 'device' ? ' [device]' : '';
+                lines.push(`    ${id(rule.id)}["${rule.id}${mark}"]`);
+            }
+            lines.push('  end');
+            lines.push(`  SKILL --> ${node}_g`);
+            continue;
+        }
+        lines.push(`  SKILL --> ${node}["${heuristic.file} (${tier}, ${heuristic.rules.length})"]`);
+    }
+    for (const [key, count] of crossReferences(graph)) {
+        const [from, to] = key.split(' ');
+        lines.push(`  ${id(from)} -.->|${count}| ${id(to)}`);
+    }
+    for (const file of graph.index.references) {
+        const linked = new Set(graph.links
+            .filter((link) => link.target === file && link.file.startsWith('heuristics/'))
+            .map((link) => basename(link.file, '.md')));
+        lines.push(`  ${id(file)}(["${file}"])`);
+        for (const from of linked) {
+            lines.push(`  ${id(from)} --> ${id(file)}`);
+        }
+    }
+    return lines.join('\n');
+}
+function text(graph, only) {
+    const base = graph.index.base.map((path) => basename(path, '.md'));
+    const lines = ['SKILL.md'];
+    lines.push('  flow');
+    for (const file of graph.index.flow) {
+        lines.push(`    ${file}`);
+    }
+    for (const tier of ['base', 'extra']) {
+        lines.push(`  ${tier}`);
+        for (const heuristic of graph.heuristics) {
+            const isBase = base.includes(heuristic.file);
+            if ((tier === 'base') !== isBase) {
+                continue;
+            }
+            lines.push(`    ${heuristic.file} (${heuristic.rules.length} rules)`);
+            if (!only.includes(heuristic.file)) {
+                continue;
+            }
+            for (const rule of heuristic.rules) {
+                const mark = rule.evidence === 'device' ? ' [device]' : '';
+                lines.push(`      ${rule.id}${mark}  line ${rule.line}, check ${rule.checkLine}`);
+            }
+        }
+    }
+    lines.push('  references');
+    for (const file of graph.index.references) {
+        const count = graph.links.filter((link) => link.target === file && link.file !== 'SKILL.md').length;
+        lines.push(`    ${file} (${count} link${count === 1 ? '' : 's'})`);
+    }
+    return lines.join('\n');
+}
+export async function graph(options) {
+    const format = options.format ?? 'mermaid';
+    if (!FORMATS.includes(format)) {
+        console.error(`unknown --format "${format}", expected ${FORMATS.join(', ')}`);
+        return 1;
+    }
+    const model = await readGraph();
+    const only = options.only ?? [];
+    if (format === 'json') {
+        console.log(JSON.stringify(model, undefined, '\t'));
+        return 0;
+    }
+    console.log(format === 'text' ? text(model, only) : mermaid(model, only));
+    return 0;
+}