@erclx/aitk 0.93.0 → 0.94.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.93.0",
+  "version": "0.94.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-docs/SKILL.md

@@ -217,7 +217,7 @@ Write the retarget as a markdown link, `Plan: [feature-<slug>](../plans-archive/
 
 If `.claude/review/review-<slug>.md` exists, delete it. `claude-review` writes with this convention. Do not sweep any other `review-*.md` file.
 
-Do not sweep `ui-checklist-*.md` (pending human verification) or `ux-audit-*.md` (standalone deliverable).
+Do not sweep `ui-checklist-*.md` (pending human verification), `ux-audit-*.md`, or `ux-measure-*.md` (standalone deliverables).
 
 Output one line per file swept:
 

package/claude/skills/claude-ux-audit/REQUIREMENT.md

@@ -37,3 +37,4 @@ The pass slides into fixing what it finds, and then the audit and the change lan
 - Feature planning, which `claude-feature` owns
 - Verifying one specific change, which `claude-ui-test` owns
 - Defining the intent it audits against, which `claude-design-extract` and the wireframes own
+- Measuring what a running interface costs to paint, block, or shift, which `claude-ux-measure` owns. Contrast stays here rather than going with it, being computable from two color values this skill already reads off the token table.

package/claude/skills/claude-ux-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: claude-ux-audit
-description: Audits the current UI for incomplete, inconsistent, or confusing patterns. Reads DESIGN.md and .claude/wireframes/ for intent, scans UI files, and outputs observations grouped by surface. Use when asked "audit the UX", "audit the UI", "UX audit", or "find UI roughness". Do NOT use for new feature planning or code changes.
+description: Audits the current UI for incomplete, inconsistent, or confusing patterns. Reads DESIGN.md and .claude/wireframes/ for intent, scans UI files, and outputs observations grouped by surface. Use when asked "audit the UX", "audit the UI", "UX audit", or "find UI roughness". Do NOT use for new feature planning or code changes, and do NOT use to measure what a running interface costs to paint, which is `claude-ux-measure`.
 ---
 
 # Claude UX audit
@@ -8,6 +8,7 @@ description: Audits the current UI for incomplete, inconsistent, or confusing pa
 ## Guards
 
 - If no UI files exist in the project (no JSX, TSX, Vue, Svelte, or HTML under `src/`), stop: `❌ No UI surfaces found to audit.`
+- If the request asks what the interface costs to paint, block, or shift at runtime, run nothing and name `claude-ux-measure`. This skill reads source and reaches no number a browser produces. Contrast is the exception and stays here, since it is computable from the two color values already in the token table.
 
 ## Step 1: read context
 

package/claude/skills/claude-ux-measure/REQUIREMENT.md

@@ -0,0 +1,45 @@
+---
+name: claude-ux-measure
+description: Why a rendering cost question is answered with a number against a published threshold, and why the runner is detected rather than prescribed
+---
+
+# Claude UX measure requirement
+
+## Gap
+
+Without this skill, a session asked what a page costs answers from source. It reads component code, names a suspicious loop, and reports a judgment, so nobody learns the number and the next session repeats the guess. Nothing in the corpus starts a browser, so the question has no surface at all and lands on whichever skill matched the word "UI".
+
+A session that does start one picks a runner on the spot. The reading then comes from a browser nobody chose, cannot be compared against the next run, and disappears with the chat. A number reported with no boundary beside it is the same dead end as the judgment it replaced, because a reader holding `1.9s` and no threshold concludes nothing from it.
+
+## Must
+
+- Detect the harness the project already carries before naming any runner
+- Report a number per metric beside the threshold it is measured against and the published source of that threshold
+- Cover paint, processor, and layout cost, and name what the run left unmeasured
+- Report what the measurement needs and stop when no harness is detected, since that is a project without a runner rather than a failure here
+- Take several readings and report the median, since one load carries startup noise wider than the gap between two thresholds
+- Write the reading to the branch-derived path at the main worktree root, overwriting
+- Reach the URL before measuring against it, starting the project's own command only when nothing already answers there
+- Leave the interface stopped and the probe deleted
+
+## Must not
+
+- Install a runner, add a dependency, or write a config to make detection succeed
+- Invent a threshold, or move a published one to fit a reading
+- Report an observation about the source in place of a measurement
+- Suggest a fix for what it measured, which is a change with its own review
+- Measure anything past the three metrics, since every adjacent ask doubles the run
+
+## Guards
+
+- No command that serves an interface and no URL from the user: stop, since there is nothing to reach. Test for a servable interface rather than for source under a named folder, which refuses a project laying its tree out differently while its server sits ready
+- No harness detected: name the runners this can drive and stop
+- No URL derivable from the project's own commands: ask rather than guessing a port
+
+## Out of scope
+
+- Judging the interface against stated intent, which `claude-ux-audit` owns
+- Contrast, which is computable from two color values in the token table `claude-ux-audit` already reads. A contrast failure from a color computed at runtime stays invisible to that reader, and the cost is accepted rather than overlooked.
+- Network waterfall, bundle size, and accessibility, which no version of this measures
+- Writing behavioral tests against the interface, which `claude-ui-test` owns
+- Fixing what the reading found

package/claude/skills/claude-ux-measure/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: claude-ux-measure
+description: Measures paint, processor, and layout cost against a running interface and reports numbers against published thresholds. Detects the project's existing browser harness rather than requiring one. Use when asked "how fast is this page", "measure the UI", "what does this cost to render", "check Core Web Vitals", or "profile the interface". Do NOT use to judge UI quality by reading source, which is `claude-ux-audit`.
+---
+
+# Claude UX measure
+
+Report numbers. A sentence about what the source looks like is what this exists to replace, so every finding is a reading beside the threshold it is measured against.
+
+## Guards
+
+- If the project names no command that serves an interface and the user names no URL, stop: `❌ Nothing to serve. Name a running URL or a command that starts one.` Test for a servable interface rather than for source under a particular folder, since this measures what a browser receives and never reads the tree that produced it.
+- If the request is about intent, consistency, missing states, or contrast, run nothing and name `claude-ux-audit`. That skill reads source and this one runs the interface.
+
+## Step 1: reach the interface
+
+Read these in parallel from the project root, skipping any that do not exist:
+
+- `package.json`: the `scripts` block naming a dev, preview, or start command
+- `.claude/context/development/`: the documented run commands and the port each serves
+- `CLAUDE.md`: project type and conventions
+
+Prefer a production-shaped build (`preview`, `start`) over the dev server. A dev server ships unminified modules and reports a cost no user pays.
+
+Ask for the URL when nothing names one. Do not guess a port.
+
+Then reach it. Request the URL first and measure whatever already answers, since a server the user started is the one they mean. Build and start the chosen command only when nothing answers, wait for it to accept a request before going on, and stop it once Step 4 has the readings. A run that measures before the server is listening reports a connection failure as a cost.
+
+## Step 2: detect the harness
+
+Test each in order and take the first that resolves. Name the one found before running it.
+
+1. A connected browser MCP server exposing navigation and a performance trace
+2. `@playwright/test` or `playwright` in `package.json`, or a `playwright.config.*` at the project root
+3. `lighthouse` in `package.json`, or a script whose command names it
+
+Never install a runner, add a dependency, or write a config to make one of these resolve. The project chooses its harness and this skill reads that choice.
+
+When none resolves, report what the measurement needs and stop:
+
+```plaintext
+❌ No browser harness detected. This measurement drives one of:
+   - a browser MCP server with a performance trace
+   - Playwright (@playwright/test)
+   - Lighthouse (lighthouse)
+Install one, or name a running URL and which runner to drive it with.
+```
+
+## Step 3: measure
+
+Take three readings against the same URL on a cold profile and report the median. One load carries startup noise wider than the gap between two thresholds, so a single number cannot be placed against them.
+
+Measure these three and nothing else:
+
+- **Paint**: Largest Contentful Paint, the moment the largest element in the viewport finishes rendering
+- **Processor**: Total Blocking Time, main-thread time past 50ms per long task between first paint and interactive
+- **Layout**: Cumulative Layout Shift, the summed score of unexpected shifts over the page lifetime
+
+Through Playwright or an MCP server, read them from a `PerformanceObserver` registered before navigation against the `largest-contentful-paint`, `longtask`, and `layout-shift` entry types. Lighthouse reports all three under its JSON audits, so parse rather than re-derive them.
+
+Write any probe the harness needs into the project's own test folder, run it, then delete it. Leave no file behind.
+
+### Thresholds
+
+| Metric | Good      | Needs work | Poor      |
+| ------ | --------- | ---------- | --------- |
+| LCP    | `≤ 2.5s`  | `≤ 4.0s`   | `> 4.0s`  |
+| TBT    | `≤ 200ms` | `≤ 600ms`  | `> 600ms` |
+| CLS    | `≤ 0.1`   | `≤ 0.25`   | `> 0.25`  |
+
+These are Google's published Core Web Vitals boundaries, with the Lighthouse lab boundary for Total Blocking Time. Cite that source in the report. Never move a number to fit a reading, and never invent a fourth metric's boundary.
+
+## Step 4: report and persist
+
+### Report format
+
+```markdown
+3 metrics measured against <url> over 3 runs. Harness: <name>.
+
+| Metric | Median | Threshold | Verdict                      |
+| ------ | ------ | --------- | ---------------------------- |
+| LCP    | <n>    | `≤ 2.5s`  | <good \| needs work \| poor> |
+| TBT    | <n>    | `≤ 200ms` | <verdict>                    |
+| CLS    | <n>    | `≤ 0.1`   | <verdict>                    |
+
+Thresholds: Google Core Web Vitals, Lighthouse lab boundary for TBT.
+
+Not measured: network waterfall, bundle size, accessibility, contrast.
+```
+
+Report the reading and stop there. A remedy for a poor verdict is a change with its own review, so name no fix and edit no source.
+
+### Persist
+
+Derive `<slug>` per `.claude/standards/slug.md`, or `${CLAUDE_SKILL_DIR}/../../standards/slug.md` when the project does not have it. Fall back to `latest` on an empty result.
+
+Write the full reading directly to `.claude/review/ux-measure-<slug>.md` at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`. Create the directory if it does not exist. Always overwrite.
+
+From a linked worktree the file-editing tools refuse that path, so the reading goes out through `Bash`. Send the `mkdir -p` and the heredoc as two plain commands rather than joining them with `&&`, which is refused as compound.
+
+The `.claude/review/` directory is gitignored. Do not stage or commit the file.
+
+### Chat output
+
+Output the summary line and the file path. Do not repeat the table in chat.
+
+```plaintext
+3 metrics measured against <url>. <n> past threshold.
+📝 Wrote .claude/review/ux-measure-<slug>.md
+```

package/claude/skills/setup-gov/REQUIREMENT.md

@@ -11,12 +11,15 @@ Without this skill, a session picks a stack name from memory and installs rules
 
 The two costly failures are quieter. An unmatched technology gets the nearest rule instead of a stop, so the project carries governance authored for something adjacent and nothing marks it as a guess. A rule written directly into the target lands where no sync will ever reach it, so it drifts from the toolkit copy that owns it.
 
+The last failure sits at a boundary rather than inside a run. `setup-init` turns away a project whose language it carries no stack for and sends it here, and a body stating only what this skill does not cover leaves that route running one way, so a person arriving on it reads a skill that never says it is the destination.
+
 ## Must
 
 - Read the catalog at run time and resolve both the stack and every extra against it
 - Name the evidence file behind each detected technology in the preview, so a wrong match is visible before the install rather than after
 - Dedupe extras against the rules the picked stack already resolves
 - Run the install non-interactively, since the CLI picker blocks where no terminal is attached
+- State the inbound route from `setup-init`, so a project sent here for the language-neutral rule layer can tell it landed at the destination the chain named
 
 ## Must not
 

package/claude/skills/setup-gov/SKILL.md

@@ -7,6 +7,11 @@ description: Detects a project's stack from its files and installs matching tool
 
 Automates `aitk gov install` by inferring the stack and extras from the current project, then shelling out to the CLI with the resolved arguments.
 
+## Scope
+
+- Governance rules and nothing else. `setup-init` is the one-shot chain that installs governance beside tooling, standards, snippets, and the seeds.
+- This is where `setup-init` sends a project whose language the toolkit carries no stack for. Rules install without the `base` development dependencies the tooling layer would drop on it. Resolve and stop exactly as below, since a language with no stack is the unmatched case `## Gap handling` already owns and arriving by that route changes none of it.
+
 ## Read the catalog
 
 Run this first to load the current stacks and rules. Never hardcode names. The catalog is the source of truth.

package/claude/skills/setup-indexes/REQUIREMENT.md

@@ -11,6 +11,8 @@ Without this skill, a session bootstrapping the index system writes `index.md` i
 
 The scan is where the other failures start. A walk that does not prune reaches `node_modules`, gitignored output, and the snippets folder, which is invoked by reference rather than browsed and needs neither an index nor per-file frontmatter. A folder that already carries an `index.md` gets a second one written over the first.
 
+One failure predates the scan. `setup-init` declines an install that wants the Claude layer without the tooling chain and names this skill as where the index system gets bootstrapped, and a body that never states the inbound route leaves the person arriving on it unable to tell whether they landed at the destination or somewhere adjacent to it.
+
 Drafted frontmatter is a proposal, and a session that writes it before the user sees it turns a review into a cleanup. The convention block has the mirror failure. A session that paraphrases it into `CLAUDE.md` produces a copy that reads correctly and no longer matches its source, so the two drift with nothing reporting it. And a project with no `CLAUDE.md` gets one scaffolded to hold the block, which installs a file the project declined.
 
 ## Must
@@ -21,6 +23,7 @@ Drafted frontmatter is a proposal, and a session that writes it before the user
 - Validate with a dry run and stop on the first reported error, before writing for real
 - Paste the convention block verbatim from its single source
 - Emit the closeout exactly once, whatever the seed step concluded
+- State the inbound route from `setup-init`, so an install wanting the Claude layer without the tooling chain can tell it landed at the destination the chain named
 
 ## Must not
 

package/claude/skills/setup-indexes/SKILL.md

@@ -13,6 +13,7 @@ Read `.claude/context/indexes.md` from the toolkit if context on the system is n
 
 - Bootstrap un-indexed folders only. Skip folders that already contain an `index.md`.
 - All-or-nothing per chosen folder. Every `*.md` sibling in a chosen folder gets `title` and `description` injected, or none does. Partial migration creates folders that hard-error on regen.
+- This is where `setup-init` sends an install that wants the Claude layer without the tooling chain, once `aitk claude init` has seeded the docs. The work is the same either way, since the scan below prunes `.claude` and reads the project's own documentation folders whichever route reached it.
 
 ## Scan
 

package/claude/skills/setup-init/REQUIREMENT.md

@@ -11,12 +11,18 @@ Without this skill, a session installs a stack whose name it recalled rather tha
 
 Two failures are the expensive ones because both return success. A monorepo run drops husky into every subtree, git honors one `core.hooksPath`, and the extra hook directories go quiet with nothing reporting it. A caller reads the chain as onboarding complete when index bootstrap and plugin provisioning never ran, since no step states whether they belong to the chain.
 
+Two more start at the resolve step. A project whose language the toolkit carries no stack for resolves to `base`, and the preview reports the resolved name without marking it as a fallback, so `base` development dependencies, scripts, and hooks land on a project that will not use them and nobody had the moment to decline.
+
+The other is the refusal that ends rather than routes. An existing project, an install wanting the Claude layer without the tooling chain, and a language with no stack are the three states the chain does not serve, and each is declined by a declaration naming no destination, so the person who arrived with one reads a stop and goes no further.
+
 ## Must
 
 - Resolve every domain argument against a catalog read at run time, so a stack, rule, snippet, or tooling name the catalog does not carry cannot reach the command line
 - Preview the resolved chain before the first command runs, naming the evidence file behind each detected technology
 - Pass `--skip base` on every subtree past the first in a monorepo, so the shared hook layer lands once
 - State which onboarding steps the chain does not run, so a caller knows what is left rather than inferring completeness from a clean report
+- Mark a stack reached by fallback as a fallback in the preview, and name what `base` carries, so the write can be declined at the one point it is still declinable
+- Name a destination for every state the chain does not serve, in this body rather than only in a reference doc the person would have to already know to open, and say for each whether the chain stops or runs on a default
 
 ## Must not
 
@@ -35,3 +41,5 @@ Two failures are the expensive ones because both return success. A monorepo run
 - Provisioning Claude Code plugins: `setup-plugins`. Those install once per machine rather than into a project, so no project-scoped chain can carry them.
 - Running the verification scripts, which `setup-verify` owns and this chain invokes as its last step
 - Re-installing into a project that already has the files, which the per-domain `aitk <domain> install` and `aitk sync` commands own
+- Deciding which of those per-domain commands an existing project needs: `toolkit-operator`. That skill reads the target before naming one, which this chain never does, so it is the destination rather than a guess made here.
+- Seeding the `.claude/` folder without the tooling chain, which `aitk claude init` does on its own and `setup-indexes` finishes

package/claude/skills/setup-init/SKILL.md

@@ -12,6 +12,16 @@ Orchestrates the onboarding chain. Detects project type, resolves per-domain arg
 - This skill and `aitk init` run once on a fresh scaffold, never on an existing project. They do not guard against clobbering existing configs. When tempted to add guards, mode switches, or an existing-project branch, stop. Extend the per-domain `aitk <domain> install` or `aitk sync` paths instead.
 - The chain does not bootstrap the `index.md` system and does not provision Claude Code plugins. `setup-indexes` owns the first. `setup-plugins` owns the second, which installs once per machine rather than into a project, so no project-scoped chain can carry it. Name both in the report so a clean result does not read as onboarding complete.
 
+## Declined states
+
+Three states reach this skill that the chain does not serve. Name the destination for each, so the refusal routes rather than ends. The first two stop the chain outright and the third runs it on a default the person may not want.
+
+- **An existing project.** Stop and hand off to `toolkit-operator`. It reads what the target already carries before it names a command, which this chain never does, so any per-domain install picked here is a guess against configs nobody read. The Scope bullet above names the same commands as the authoring alternative, and this is the destination a person takes.
+- **An install wanting the `.claude/` folder alone.** Stop. Run `aitk claude init` for the seed docs, then invoke `setup-indexes` to bootstrap the `index.md` system over the project's own documentation folders. Neither needs the tooling sync this chain runs.
+- **A language the toolkit carries no stack for.** The chain still runs, on `base`, with the fallback marked in the preview. A project that wants none of what `base` carries declines there and takes `setup-gov` for the governance layer, which is language-neutral. Say so at the preview rather than resolving it here, since the fallback is a working default and only the person can say whether it fits.
+
+Do not add a stack, a mode switch, or an existing-project branch to satisfy one of these. Each destination already exists and routing to it costs a line.
+
 ## Read catalogs
 
 Run in parallel. Never hardcode stack, rule, snippet, or standards names.
@@ -36,8 +46,8 @@ Read these from the project root in parallel, skipping any that do not exist:
 
 ## Resolve arguments
 
-- **Stack:** pick the closest governance stack by matching detected runtime or framework against stack names in the catalog. If nothing matches, fall back to `base`.
-- **Tooling stack:** pick the closest tooling stack from `aitk tooling list --json` (e.g. `vite-react`, `astro`). Distinct from the governance stack. Fall back to `base` if no framework match.
+- **Stack:** pick the closest governance stack by matching detected runtime or framework against stack names in the catalog. If nothing matches, fall back to `base` and carry the fallback into the preview.
+- **Tooling stack:** pick the closest tooling stack from `aitk tooling list --json` (e.g. `vite-react`, `astro`). Distinct from the governance stack. Fall back to `base` if no framework match, and carry that fallback into the preview too.
 - **Extras:** identify technologies not already covered by the picked stack. For each, find a rule whose `description` or `paths` points at that technology and pass it via `--add`. Do not add a rule the stack already pulls in.
 - **Snippets:** default to `all`. Narrow only if the user asked for a specific category.
 - **Skip (`--skip`):** `standards` and `wiki` are core and install by default. Add `--skip standards` or `--skip wiki` only when the user explicitly wants them left out.
@@ -56,14 +66,16 @@ Rules, snippets, and stacks are authored in the toolkit repo, never in the targe
 Before executing, output:
 
 - **Detected:** each technology with its evidence file
-- **Stack:** picked governance stack + resolved rule count
-- **Tooling stack:** picked tooling stack
+- **Stack:** picked governance stack + resolved rule count. Mark it `fallback` when no detected runtime or framework matched a catalog name.
+- **Tooling stack:** picked tooling stack. Mark it `fallback` on the same test, and name what `base` lands: configs, seeds, and gitignore entries in every case, plus the JavaScript development dependencies, scripts, and hook activation wherever a `package.json` exists to carry them. A project outside that ecosystem runs none of the second group and keeps the first.
 - **Extras:** each `--add` rule with a one-line reason
 - **Snippets:** resolved category
 - **Skip:** any `--skip` entries with reason
 - **Target:** resolved target path
 - **Commands:** the full chain that will run
 
+A resolved name and a fallback read alike once written, so mark the fallback here rather than in the report. The preview is the last point before the first write, and the report runs after the files have landed.
+
 ## Execute
 
 Run the chain in order, starting immediately after the preview. Each step's permission dialog is the confirmation gate. Do not pause for additional confirmation. Run from the target project's current directory.

package/claude/skills/toolkit-operator/REQUIREMENT.md

@@ -31,6 +31,7 @@ The last failure is a section no route reaches. `## Route` maps an intent or a d
 - Route a measurement intent to the audit offers from the route table itself, rather than leaving the section reachable only by reading past the table
 - Rank a lifecycle row against the audit offers where the route table itself states it, so a session acting on the lifecycle row reads the ranking without opening the section being ranked
 - Offer every audit whose surface the target carries, and offer none whose surface it lacks
+- Hand off an audit that is a skill rather than a command, since the execute contract governs a CLI run and says nothing about a skill's own guards
 - Re-check the target after any operation that wrote, and report what those writes changed against the state read before acting
 
 ## Must not

package/claude/skills/toolkit-operator/SKILL.md

@@ -69,7 +69,7 @@ On a measured report, take `<stack>` from the first name in `tooling.chain`, whi
 
 ### Audits
 
-Four audits measure a surface without changing it. Offer the ones whose surface the target carries, list them together, and let the user pick. Run none of them unasked, and never treat a finding as a reason to abandon the operation the user asked for, since each reports judgments beside facts.
+Five audits measure a surface without changing it. Offer the ones whose surface the target carries, list them together, and let the user pick. Run none of them unasked, and never treat a finding as a reason to abandon the operation the user asked for, since each reports judgments beside facts.
 
 A lifecycle row and these offers fire together on a project carrying a context folder and no installed domain, which is the ranking the preamble states. Scaffold work on a target with nothing installed is real work, so an audit offered instead of it answers a question nobody asked, while an audit dropped in favor of it loses the one the user did.
 
@@ -77,10 +77,13 @@ A lifecycle row and these offers fire together on a project carrying a context f
 - A record folder present under `.claude/`, one of `plans`, `groundwork`, `intake`, or `memory`: offer `aitk records validate <kind>` for each one found
 - Markdown that git lists: offer `aitk markdown audit`
 - TypeScript or shell source present: offer `aitk comments scan`
+- A `package.json` script that serves an interface, one of `dev`, `preview`, `serve`, or `start`: offer `claude-ux-measure`
 
 An audit offered against a surface the target lacks reports an empty run as a finding, which is the same defect as never offering it at all. Check the surface before naming the command.
 
-The markdown row is the one every target satisfies, since a project with no markdown is not one this reaches. Its condition is stated so the four rows read alike, and the row needs no gate beyond it.
+The markdown row is the one every target satisfies, since a project with no markdown is not one this reaches. Its condition is stated so the five rows read alike, and the row needs no gate beyond it.
+
+The last row is a skill handoff rather than a command, so `## Execute` does not govern it. Hand it off and stop, the way a lifecycle row hands off. Its condition reads a serving command rather than a source folder, since that skill measures what a browser receives and never opens the tree behind it. It carries a second condition this skill cannot read, which is a browser harness the project already installed, and the skill itself reports what it needs when it finds none. Testing for that here would put the detection in two places and let this one answer stale.
 
 ## Execute
 

package/docs/ai-workflow.md

@@ -181,6 +181,7 @@ Before the first feature session on a UI-heavy project, pick a design tier. The
 | `aitk:claude-docs`           | When decisions diverged from plan, update `.claude/` docs                                                            |
 | `aitk:claude-ui-test`        | After UI changes, generate and run e2e tests + visual checklist                                                      |
 | `aitk:claude-ux-audit`       | Audit existing UI surfaces for missing states, edge cases, inconsistencies                                           |
+| `aitk:claude-ux-measure`     | Measure paint, processor, and layout cost against a running interface, on the harness the project already carries    |
 | `aitk:claude-autoship`       | After plan approval, chain implement → verify → review → draft PR                                                    |
 | `aitk:systematic-debugging`  | When a test fails or bug surfaces, enforce root-cause investigation before fixes                                     |
 | `aitk:git-ship`              | Post-feature: sync docs, commit, rename branch, open PR                                                              |

package/docs/target-projects.md

@@ -49,6 +49,8 @@ The chain is:
 - The agent follows the reference to generate eslint, vitest, playwright configs and the stack's setup script, and extends `.claude/context/ci.md` and `.claude/context/development.md` per the reference's extend sections <!-- audit-ignore-citations -->
 - `setup-verify` runs the installed `package.json` scripts (lint, typecheck, check, test, build) and reports pass or fail
 
+The chain serves a fresh scaffold and names a destination for the three states it does not. An existing project goes to `aitk:toolkit-operator`, which reads what the project already carries before naming a per-domain command. An install wanting the Claude layer without the tooling chain runs `aitk claude init` for the seed docs and then `aitk:setup-indexes` for the index system. A language the toolkit ships no stack for is the one of the three the chain still runs for, on `base`, with the fallback marked in the preview so it can be declined there.
+
 Keep the `## Scripts` table in `.claude/context/development.md` current as scripts are added. Base tooling seeds that entry with the commands it installs, and each stack reference extends the table. `project-commands` reads it to start the app or run a check on request, so a command missing from the table cannot be run that way. A project whose entry outgrew one file and split into `.claude/context/development/` keeps the table in `overview.md`, which is where the skill looks next. <!-- audit-ignore-citations -->
 
 ### From scaffold to first feature
@@ -76,6 +78,8 @@ Escalate only for real web apps. The `setup-init` skill reads `package.json` and
 
 Markdown-heavy projects, CLI tools, docs sites, research notebooks, and scripting repos stay on `base`. Escalation is a ceiling move, not a default.
 
+A project the toolkit ships no stack for lands on `base` the same way, and the skill marks that resolution as a fallback in its preview rather than reporting it as a match. Configs, seeds, and gitignore entries land either way, and the JavaScript development dependencies, scripts, and hook activation land only where a `package.json` exists to carry them. A project outside that ecosystem declines at the preview and takes `aitk:setup-gov` for the governance layer alone, which is language-neutral.
+
 Run `aitk tooling list --json` and `aitk gov list --json` to see the current catalogs. Never hardcode stack names.
 
 ### Core domains and skips
@@ -174,7 +178,7 @@ cd <your-project>
 claude
 ```
 
-In the session, invoke `aitk:setup-init`. The skill detects no framework, resolves tooling to `base`, governance to `base`, snippets to `all`, and auto-enables `standards` if `docs/` exists. It previews the chain, then runs `aitk init`.
+In the session, invoke `aitk:setup-init`. The skill detects no framework, resolves tooling to `base`, governance to `base`, snippets to `all`, and auto-enables `standards` if `docs/` exists. The preview marks both stacks as fallbacks, since neither came from a match, then the chain runs `aitk init`.
 
 Ongoing: run `aitk sync --check .` to see what has drifted, then invoke `aitk:claude-seed-sync` for seed drift or `aitk sync .` for a catch-all refresh.
 

package/docs/visual-design-workflow.md

@@ -34,6 +34,7 @@ The `aitk:claude-design-extract` skill drafts the file, sourcing tokens from a p
 - `aitk:claude-design-extract` to draft `.claude/DESIGN.md`, from existing project signals or from requirements alone on day one
 - `aitk:claude-ui-test` for e2e test generation after UI changes
 - `aitk:claude-ux-audit` for UX gap detection on existing surfaces
+- `aitk:claude-ux-measure` for what a running surface costs to paint, read against published thresholds
 - Anthropic's `frontend-design` plugin optional for light visual steering
 
 ### When to pick

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.93.0",
+  "version": "0.94.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {