@erclx/aitk 3.27.0 → 3.28.0

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

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

package/docs/agents/commands.md

@@ -59,11 +59,22 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk census [path]`       | Report tracked file count, a breakdown by extension, and a line total that skips whatever reads as binary (`--json`)                                                 |
 | `aitk audits run`          | Run every audit as one set, report per check under one verdict, and compare each count to the recorded baseline (`--json`, `--record`)                               |
 | `aitk audits list`         | List every audit the set runs, with the corpus each reads and whether it gates (`--json`)                                                                            |
+| `aitk inventory [subject]` | Walk every route a project declares and group its elements by the property each computes, as a listing rather than a gate (`--json`)                                 |
 | `aitk capture [source]`    | Render HTML capture sources to PNG, toolkit-only and absent from an installed package                                                                                |
 | `aitk upgrade`             | Reinstall the CLI globally with the package manager the install path names (`--json`)                                                                                |
 
 `aitk demo` is the second browser command and the one that ships, since its purpose is running in a target rather than regenerating what this repository commits. It needs a browser binary the package does not carry, installed once with `bunx playwright install chromium`.
 
+`aitk inventory` is the third and takes the same answer for the same reason. It reads `inventory.toml` at the project root for its base URL, its routes, and the element query each subject runs over, so what it walks comes from the project rather than from the toolkit. It reports how many different answers a site gives for one property and never gates, because whether five focus rings across four routes is a defect is a judgment. A missing server and an unmatched query are both refusals rather than empty listings, since a listing with no rows reads as one consistent answer.
+
+```toml
+base-url = "http://localhost:4173"
+routes = ["/", "/pricing", "/docs"]
+
+[subjects.focus]
+query = "button, a[href], input, select, textarea, [tabindex]"
+```
+
 ## Domain commands
 
 Each domain exposes a consistent shape where applicable: `list`, `install`, `sync`, `create`.
@@ -76,6 +87,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | `gov`       | `list`, `install`, `sync`, `build`, `regen`, `test-order`, `superseded`                                                               |
 | `claude`    | `init`, `sync`, `routing`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `skills reach`, `skills rank`, `setup [dest]` |
 | `demo`      | `compile`, `run`                                                                                                                      |
+| `inventory` | `run`                                                                                                                                 |
 | `wiki`      | `init`                                                                                                                                |
 | `design`    | `render`                                                                                                                              |
 | `slides`    | `render`, `list`                                                                                                                      |

package/package.json

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

package/src/browser/engine.ts

@@ -0,0 +1,40 @@
+/**
+ * What every browser-driving command needs to know before it can report a
+ * failure honestly: how the binary is installed, and how each of the two ways
+ * it can be absent reads when it is thrown.
+ *
+ * The two are different states with different remedies. A package that never
+ * resolved means the target installed the CLI without the engine, and a binary
+ * that was never downloaded means the engine is present and its browser is not.
+ * Both were spelled inside `src/demo/` when `demo` was the only command driving
+ * a browser, and a second command is what makes them shared rather than local.
+ */
+
+/** Fetches the browser revision the pinned engine expects. */
+export const INSTALL_BROWSER = 'bunx playwright install chromium'
+
+/**
+ * Separates a browser binary that was never installed from every other launch
+ * failure, because the first is a setup step the operator has to run and the
+ * second is a defect. A target inherits that setup step, which is the stated
+ * cost of shipping a browser command outside the toolkit.
+ */
+export function isBrowserMissing(error: unknown): boolean {
+  const text = error instanceof Error ? error.message : String(error)
+  return /executable doesn't exist|playwright install/i.test(text)
+}
+
+/**
+ * Reports the engine package failing to resolve, which is the case a target
+ * hits before installing it. Any other import failure is a defect inside the
+ * module being loaded and propagates, rather than being reported as a missing
+ * dependency.
+ */
+export function isEngineMissing(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    error.code === 'ERR_MODULE_NOT_FOUND'
+  )
+}

package/src/cli.ts

@@ -16,6 +16,7 @@ import { register as design } from '@/commands/design'
 import { register as slides } from '@/commands/slides'
 import { register as capture } from '@/commands/capture'
 import { register as demo } from '@/commands/demo'
+import { register as inventory } from '@/commands/inventory'
 import { register as feedback } from '@/commands/feedback'
 import { register as transcripts } from '@/commands/transcripts'
 import { register as tasks } from '@/commands/tasks'
@@ -59,6 +60,7 @@ function showHelp(): void {
     `${GREY}│${NC}    slides [cmd]       ${GREY}# Slide deck commands (render, list)${NC}`,
     `${GREY}│${NC}    capture [source]   ${GREY}# Render HTML capture sources to PNG${NC}`,
     `${GREY}│${NC}    demo [cmd]         ${GREY}# Record a running app (compile, run)${NC}`,
+    `${GREY}│${NC}    inventory [subj]   ${GREY}# Report one computed property across every route${NC}`,
     `${GREY}│${NC}    feedback           ${GREY}# Write toolkit feedback from stdin to .claude/review/feedback/${NC}`,
     `${GREY}│${NC}    transcripts <url>  ${GREY}# Fetch a YouTube transcript with metadata frontmatter${NC}`,
     `${GREY}│${NC}    tasks [cmd]        ${GREY}# Task board commands (archive)${NC}`,
@@ -102,6 +104,7 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk slides render`,
     `${GREY}│${NC}    aitk slides list --json`,
     `${GREY}│${NC}    aitk capture assets/install.html`,
+    `${GREY}│${NC}    aitk inventory focus --json`,
     `${GREY}│${NC}    pbpaste | aitk feedback`,
     `${GREY}│${NC}    aitk transcripts https://youtu.be/VIDEO_ID`,
     `${GREY}│${NC}    aitk tasks archive --pull-request 673 --json`,
@@ -153,6 +156,7 @@ design(program)
 slides(program)
 capture(program)
 demo(program)
+inventory(program)
 feedback(program)
 transcripts(program)
 tasks(program)

package/src/commands/demo.ts

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { basename, dirname, extname, join, relative, resolve } from 'node:path'
 import type { Command } from 'commander'
+import { INSTALL_BROWSER, isEngineMissing } from '@/browser/engine'
 import { parseDraft } from '@/demo/beats'
 import { compilePlan, parsePlan, unresolved } from '@/demo/compile'
 import { convertToMp4, INSTALL_CONVERTER } from '@/demo/container'
@@ -9,7 +10,6 @@ import { loadCursorTheme } from '@/demo/theme'
 import { intro, logError, logInfo, logStep, logWarn, outro, plural } from '@/ui'
 
 const DEFAULT_OUT = 'demos'
-const INSTALL_BROWSER = 'bunx playwright install chromium'
 
 /**
  * Holds wiring only. Every browser reference sits behind `loadDriver`, because
@@ -359,20 +359,11 @@ async function loadDriver(): Promise<Driver | undefined> {
   try {
     return await import('@/demo/drive')
   } catch (error) {
-    if (isModuleNotFound(error)) return undefined
+    if (isEngineMissing(error)) return undefined
     throw error
   }
 }
 
-function isModuleNotFound(error: unknown): boolean {
-  return (
-    typeof error === 'object' &&
-    error !== null &&
-    'code' in error &&
-    error.code === 'ERR_MODULE_NOT_FOUND'
-  )
-}
-
 /**
  * Resolves where one artifact lands. `--out` replaces the directory the plan
  * names rather than acting as a root the plan's own directory hangs off, which

package/src/commands/inventory.ts

@@ -0,0 +1,256 @@
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import { INSTALL_BROWSER, isEngineMissing } from '@/browser/engine'
+import {
+  CONFIG_REL,
+  type ConfigRefusal,
+  readInventoryConfig,
+} from '@/inventory/config'
+import { abbreviate, groupByTreatment } from '@/inventory/group'
+import { findSubject, SUBJECTS } from '@/inventory/subjects'
+import type { WalkRefusal } from '@/inventory/walk'
+import { intro, logError, logInfo, logStep, logWarn, outro, plural } from '@/ui'
+
+/**
+ * Holds wiring only. Every browser reference sits behind `loadWalker`, because
+ * `src/cli.ts` imports this module at startup and resolving the engine there
+ * would put a browser launch in front of every other command.
+ */
+type Walker = typeof import('@/inventory/walk')
+
+interface RunOptions {
+  readonly root?: string
+  readonly baseUrl?: string
+  readonly json?: boolean
+}
+
+/** What a reader does about each way the config produced no walk. */
+const CONFIG_REFUSALS: Record<ConfigRefusal, string> = {
+  'no-config': `No ${CONFIG_REL} here, so no routes and no element query are declared.`,
+  'unreadable-config': `${CONFIG_REL} is not valid TOML, so no route could be read.`,
+  'no-routes': `${CONFIG_REL} carries no route under routes, so there is nothing to walk.`,
+  'no-base-url': `${CONFIG_REL} carries no base-url, so no route resolves to an address.`,
+  'no-subjects': `${CONFIG_REL} declares no subject, and the element query comes from this project rather than from the toolkit.`,
+}
+
+const WALK_REFUSALS: Record<WalkRefusal, string> = {
+  'browser-missing': 'The browser binary is not installed in this project.',
+  'server-unreachable':
+    'Nothing answered at the base URL, so no route was read.',
+  'walk-failed': 'The walk failed against a running server.',
+}
+
+export function register(program: Command): void {
+  const inventory = program
+    .command('inventory')
+    .description('Report one computed property across every route of a project')
+    .helpOption('-h, --help', 'Show this help message')
+
+  inventory
+    .command('run', { isDefault: true })
+    .description(
+      'Walk every route and group its elements by the answer each gives',
+    )
+    .argument('[subject]', 'Treatment to read, defaulting to focus', 'focus')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Project to read, defaulting to the cwd')
+    .option('--base-url <url>', 'Address to walk, overriding the config')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        `Reads ${CONFIG_REL} for the base URL, the routes, and the element query`,
+        'each subject runs over, so what gets walked comes from the project',
+        'rather than from the toolkit.',
+        '',
+        'It reports a listing and never a verdict. The value is seeing how many',
+        'different answers one site gives, and a gate collapses that to one bit.',
+        '',
+        'Needs a running server and a browser binary. Install the browser with:',
+        `  ${INSTALL_BROWSER}`,
+        '',
+        'Subjects:',
+        ...SUBJECTS.map((subject) => `  ${subject.name}  ${subject.summary}`),
+        '',
+        'Exit codes:',
+        '  0  the walk read at least one element and reported its rows',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Examples:',
+        '  aitk inventory focus',
+        '  aitk inventory focus --json',
+        '  aitk inventory focus --base-url http://localhost:3000',
+        '',
+      ].join('\n'),
+    )
+    .action(async (subject: string, opts: RunOptions) => {
+      process.exitCode = await runInventory(subject, opts)
+    })
+}
+
+async function runInventory(
+  subjectName: string,
+  opts: RunOptions,
+): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro(`aitk inventory ${subjectName}`)
+
+  const subject = findSubject(subjectName)
+  if (!subject) {
+    const known = SUBJECTS.map((entry) => entry.name).join(', ')
+    return refuse(
+      emitJson,
+      root,
+      'unknown-subject',
+      `No reader named ${subjectName}. This build ships: ${known}.`,
+    )
+  }
+
+  const read = readInventoryConfig(root)
+  if (read.kind === 'refused') {
+    return refuse(emitJson, root, read.reason, CONFIG_REFUSALS[read.reason])
+  }
+
+  const declared = read.config.subjects.find(
+    (entry) => entry.name === subjectName,
+  )
+  if (!declared) {
+    const named = read.config.subjects.map((entry) => entry.name).join(', ')
+    return refuse(
+      emitJson,
+      root,
+      'undeclared-subject',
+      `${CONFIG_REL} declares no query for ${subjectName}. It declares: ${named}.`,
+    )
+  }
+
+  const baseUrl = opts.baseUrl ?? read.config.baseUrl
+
+  logStep('Scope')
+  logInfo(
+    `${plural(read.config.routes.length, 'route')} from ${baseUrl}, matching ${declared.query}`,
+  )
+
+  const walker = await loadWalker()
+  if (!walker) {
+    logStep('Browser')
+    logError('the browser engine is not installed in this project')
+    logWarn(`Install it with: ${INSTALL_BROWSER}`)
+    outro()
+    emit(emitJson, {
+      root,
+      subject: subjectName,
+      reason: 'engine-missing',
+      install: INSTALL_BROWSER,
+    })
+    return 1
+  }
+
+  const result = await walker.walk({
+    baseUrl,
+    routes: read.config.routes,
+    subject,
+    query: declared.query,
+  })
+
+  if (result.status === 'failed') {
+    logStep('Refused')
+    logWarn(WALK_REFUSALS[result.reason])
+    if (result.reason === 'server-unreachable') {
+      logWarn(`Start the project at ${baseUrl}, then run this again.`)
+    }
+    if (result.reason === 'browser-missing') {
+      logWarn(`Install the browser binary with: ${INSTALL_BROWSER}`)
+    }
+    logWarn(result.message.split('\n')[0] ?? '')
+    outro()
+    emit(emitJson, {
+      root,
+      subject: subjectName,
+      baseUrl,
+      reason: result.reason,
+      message: result.message,
+      ...(result.reason === 'browser-missing'
+        ? { install: INSTALL_BROWSER }
+        : {}),
+    })
+    return 1
+  }
+
+  const groups = groupByTreatment(result.readings)
+
+  logStep('Routes')
+  for (const route of result.routes) {
+    logInfo(`${route.route}  ${plural(route.elements, 'element')}`)
+  }
+
+  // A walk that matched nothing refuses rather than printing an empty listing,
+  // because no rows and one row read the same to anything counting them, and
+  // the first says the query reached nothing while the second says the site
+  // gives one consistent answer.
+  if (groups.length === 0) {
+    return refuse(
+      emitJson,
+      root,
+      'no-elements',
+      `No element matched ${declared.query} on any of the ${plural(result.routes.length, 'route')} walked.`,
+    )
+  }
+
+  logStep('Treatments')
+  logInfo(
+    `${plural(groups.length, 'answer')} across ${plural(result.readings.length, 'element')}`,
+  )
+  for (const group of groups) {
+    logInfo(`  ${group.count}x  ${group.treatment}`)
+    logInfo(
+      `      ${abbreviate(group.samples, group.count)} on ${abbreviate(group.routes, group.routes.length)}`,
+    )
+  }
+  outro()
+
+  emit(emitJson, {
+    root,
+    subject: subjectName,
+    baseUrl,
+    routes: result.routes,
+    elements: result.readings.length,
+    treatments: groups,
+    durationMs: result.durationMs,
+  })
+  return 0
+}
+
+/**
+ * Frames a refusal on stderr and puts the record on stdout, so an operator
+ * reading the terminal sees the reason rather than a command that appeared to
+ * do nothing.
+ */
+function refuse(
+  emitJson: boolean,
+  root: string,
+  reason: string,
+  message: string,
+): number {
+  logStep('Refused')
+  logWarn(message)
+  outro()
+  emit(emitJson, { root, reason, message })
+  return 1
+}
+
+async function loadWalker(): Promise<Walker | undefined> {
+  try {
+    return await import('@/inventory/walk')
+  } catch (error) {
+    if (isEngineMissing(error)) return undefined
+    throw error
+  }
+}
+
+function emit(json: boolean, record: unknown): void {
+  if (json) process.stdout.write(`${JSON.stringify(record)}\n`)
+}

package/src/demo/drive.ts

@@ -3,6 +3,7 @@ import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { chromium } from 'playwright-core'
 import type { Browser, BrowserContext, Page } from 'playwright-core'
+import { isBrowserMissing } from '@/browser/engine'
 import { deriveSteps } from '@/demo/compile'
 import type { DemoPlan, DemoStep } from '@/demo/compile'
 import type { CursorSet } from '@/demo/pointer'
@@ -181,20 +182,17 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
 }
 
 /**
- * Separates a browser binary that was never installed from every other launch
- * failure, because the first is a setup step the operator has to run and the
- * second is a defect. A target inherits that setup step, which is the stated
- * cost of shipping this command outside the toolkit.
+ * Reads the launch through `@/browser/engine`, which is where the separation
+ * between a binary that was never installed and every other launch failure now
+ * lives. It moved out of this file when `aitk inventory` became the second
+ * command needing it, rather than being copied.
  */
 async function launch(): Promise<Launch> {
   try {
     return { status: 'launched', value: await chromium.launch() }
   } catch (error) {
-    const text = error instanceof Error ? error.message : String(error)
     return failed(
-      /executable doesn't exist|playwright install/i.test(text)
-        ? 'browser-missing'
-        : 'drive-failed',
+      isBrowserMissing(error) ? 'browser-missing' : 'drive-failed',
       error,
     )
   }

package/src/inventory/config.ts

@@ -0,0 +1,117 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Where a project declares what an inventory walks, spelled once.
+ *
+ * It sits at the project root rather than under `.claude/`, because the routes
+ * and the element queries describe the application rather than the agent
+ * surface, and a target reads them the way it reads any other build input.
+ */
+export const CONFIG_REL = 'inventory.toml'
+
+/** One measurable treatment and the elements that carry it, as the project spells them. */
+export interface InventorySubject {
+  readonly name: string
+  readonly query: string
+}
+
+export interface InventoryConfig {
+  readonly baseUrl: string
+  readonly routes: readonly string[]
+  readonly subjects: readonly InventorySubject[]
+}
+
+/**
+ * Why a config could not be used, which is never the same as a walk that read
+ * nothing.
+ *
+ * Every value here is a refusal rather than an empty listing, because a listing
+ * with no rows reads as a site giving one consistent answer, which is the
+ * report an unconfigured project would get for free and the exact wrong reading.
+ */
+export type ConfigRefusal =
+  | 'no-config'
+  | 'unreadable-config'
+  | 'no-base-url'
+  | 'no-routes'
+  | 'no-subjects'
+
+export type ConfigRead =
+  | { readonly kind: 'config'; readonly config: InventoryConfig }
+  | { readonly kind: 'refused'; readonly reason: ConfigRefusal }
+
+function readSubjects(table: unknown): InventorySubject[] {
+  if (typeof table !== 'object' || table === null || Array.isArray(table)) {
+    return []
+  }
+
+  const subjects: InventorySubject[] = []
+  for (const [name, value] of Object.entries(table)) {
+    if (typeof value !== 'object' || value === null) continue
+    const query = (value as Record<string, unknown>).query
+    if (typeof query !== 'string' || query === '') continue
+    subjects.push({ name, query })
+  }
+
+  return subjects
+}
+
+/**
+ * Parses config text, so a caller holding the bytes skips the filesystem.
+ *
+ * A malformed route or subject is dropped rather than refused, matching the row
+ * handling in `@/labels/map`: one bad entry should not blind the walk to the
+ * other twenty. What that costs is a typo reading as an entry nobody wrote,
+ * which the listing surfaces from the other side as a route with no elements.
+ */
+export function parseInventoryConfig(source: string): ConfigRead {
+  let parsed: Record<string, unknown>
+  try {
+    parsed = Bun.TOML.parse(source) as Record<string, unknown>
+  } catch {
+    return { kind: 'refused', reason: 'unreadable-config' }
+  }
+
+  const baseUrl = parsed['base-url']
+  if (typeof baseUrl !== 'string' || baseUrl === '') {
+    return { kind: 'refused', reason: 'no-base-url' }
+  }
+
+  const routes = Array.isArray(parsed.routes)
+    ? parsed.routes.filter(
+        (route): route is string => typeof route === 'string' && route !== '',
+      )
+    : []
+  if (routes.length === 0) return { kind: 'refused', reason: 'no-routes' }
+
+  const subjects = readSubjects(parsed.subjects)
+  if (subjects.length === 0) return { kind: 'refused', reason: 'no-subjects' }
+
+  return { kind: 'config', config: { baseUrl, routes, subjects } }
+}
+
+/** Reads the config a project declares at `root`, or says why it could not. */
+export function readInventoryConfig(root: string): ConfigRead {
+  let source: string
+  try {
+    source = readFileSync(join(root, CONFIG_REL), 'utf8')
+  } catch {
+    return { kind: 'refused', reason: 'no-config' }
+  }
+
+  return parseInventoryConfig(source)
+}
+
+/**
+ * Joins a base and a route into the address a walk opens.
+ *
+ * Concatenation rather than `new URL(route, base)`, because the resolver reads
+ * a leading slash as absolute and drops any path the base already carries, so a
+ * project served under a subdirectory would have every route walk the origin.
+ */
+export function routeUrl(baseUrl: string, route: string): string {
+  const base = baseUrl.replace(/\/+$/, '')
+  const path = route.startsWith('/') ? route : `/${route}`
+  return `${base}${path}`
+}

package/src/inventory/group.ts

@@ -0,0 +1,76 @@
+/**
+ * How many elements a row names before it stops naming them. A row exists to
+ * say how many answers a site gives, and the elements under it are there to
+ * make one findable rather than to enumerate the set.
+ */
+export const SAMPLE_LIMIT = 3
+
+/**
+ * Names a bounded head of a list and says how many it left out, so a treatment
+ * carried by fifty routes reads as fifty rather than as the three named.
+ *
+ * `total` arrives separately because the two lists reach here differently. A
+ * row's samples are already capped when they are collected, so their own length
+ * cannot say how many elements the row covers, while its routes arrive whole.
+ */
+export function abbreviate(entries: readonly string[], total: number): string {
+  const head = entries.slice(0, SAMPLE_LIMIT)
+  const elided = total - head.length
+  return elided > 0 ? `${head.join(', ')} and ${elided} more` : head.join(', ')
+}
+
+/** One element as the walk read it, on the route it was read from. */
+export interface Reading {
+  readonly route: string
+  readonly selector: string
+  readonly treatment: string
+}
+
+/** One answer the site gives, and what carries it. */
+export interface TreatmentGroup {
+  readonly treatment: string
+  readonly count: number
+  readonly routes: readonly string[]
+  readonly samples: readonly string[]
+}
+
+/**
+ * Turns a per-element walk into a per-answer listing, which is the whole point
+ * of the command.
+ *
+ * Grouping by the component instead was the obvious shape and it reports what a
+ * reader already knows, that a site has buttons and links. Grouping by the
+ * computed answer reports the thing nobody can see while building, which is
+ * that five components resolved to five different rings.
+ *
+ * Order is heaviest first, then by treatment, so the dominant answer leads and
+ * two runs over one site report one order rather than whatever the walk hit.
+ */
+export function groupByTreatment(
+  readings: readonly Reading[],
+): readonly TreatmentGroup[] {
+  const byTreatment = new Map<
+    string,
+    { count: number; routes: string[]; samples: string[] }
+  >()
+
+  for (const { route, selector, treatment } of readings) {
+    const row = byTreatment.get(treatment) ?? {
+      count: 0,
+      routes: [],
+      samples: [],
+    }
+    row.count += 1
+    if (!row.routes.includes(route)) row.routes.push(route)
+    if (row.samples.length < SAMPLE_LIMIT) row.samples.push(selector)
+    byTreatment.set(treatment, row)
+  }
+
+  return [...byTreatment.entries()]
+    .map(([treatment, row]) => ({ treatment, ...row }))
+    .sort(
+      (left, right) =>
+        right.count - left.count ||
+        left.treatment.localeCompare(right.treatment),
+    )
+}

package/src/inventory/subjects.ts

@@ -0,0 +1,114 @@
+/**
+ * The readers an inventory can run, one per treatment.
+ *
+ * A reader runs inside the page rather than here, so each one is serialized to
+ * source and evaluated by the browser. That is why every helper a reader needs
+ * is declared inside its own body: a reference to anything at module scope
+ * survives typechecking and throws once the page tries to call it.
+ *
+ * `focus` is the first and, for now, the only subject. The four sibling
+ * instruments this shape was lifted from differ only in their element query and
+ * the property they read, which is what makes a subject a row here rather than
+ * a command of its own.
+ */
+
+/** One element as a reader saw it, before any grouping. */
+export interface SubjectReading {
+  readonly selector: string
+  readonly treatment: string
+}
+
+export interface Subject {
+  readonly name: string
+  /** What the listing means, printed above the rows so a count reads correctly. */
+  readonly summary: string
+  readonly read: (query: string) => SubjectReading[]
+}
+
+/**
+ * Reports what each element changes about itself when it takes focus, which is
+ * the reading `governance/rules/ui/410-a11y.md` states three rules against and
+ * nothing measures.
+ *
+ * The difference between rest and focus is the treatment, rather than the
+ * focused style on its own. A card carrying a resting shadow computes a shadow
+ * either way, so reading only the focused state would report a ring on an
+ * element whose appearance never moves.
+ *
+ * An element the browser refuses to focus is named as such rather than folded
+ * into the no-treatment row, since a disabled control and a control with no
+ * ring are different findings with different remedies.
+ */
+function readFocusTreatments(query: string): SubjectReading[] {
+  const PROPERTIES = [
+    'outlineStyle',
+    'outlineWidth',
+    'outlineColor',
+    'outlineOffset',
+    'boxShadow',
+    'borderColor',
+    'backgroundColor',
+    'color',
+  ] as const
+
+  const describe = (element: Element): string => {
+    const tag = element.tagName.toLowerCase()
+    if (element.id) return `${tag}#${element.id}`
+    const className = element.getAttribute('class')?.trim().split(/\s+/)[0]
+    return className ? `${tag}.${className}` : tag
+  }
+
+  const snapshot = (element: Element): Record<string, string> => {
+    const computed = getComputedStyle(element)
+    const values: Record<string, string> = {}
+    for (const property of PROPERTIES) values[property] = computed[property]
+    return values
+  }
+
+  const rows: SubjectReading[] = []
+
+  // The walk presses Tab before this runs, which leaves one element focused.
+  // Reading that element's rest state while it holds focus reports no
+  // difference and hides whatever ring it actually draws, so the page starts
+  // from nothing focused and every element is blurred again after its turn.
+  const entryFocus = document.activeElement
+  if (entryFocus instanceof HTMLElement) entryFocus.blur()
+
+  for (const element of Array.from(document.querySelectorAll(query))) {
+    if (!(element instanceof HTMLElement)) continue
+
+    const rest = snapshot(element)
+    element.focus()
+    if (document.activeElement !== element) {
+      rows.push({ selector: describe(element), treatment: 'not focusable' })
+      continue
+    }
+
+    const focused = snapshot(element)
+    const changed = PROPERTIES.filter(
+      (property) => rest[property] !== focused[property],
+    ).map((property) => `${property} ${focused[property]}`)
+
+    rows.push({
+      selector: describe(element),
+      treatment:
+        changed.length === 0 ? 'no visible change' : changed.join(', '),
+    })
+    element.blur()
+  }
+
+  return rows
+}
+
+const FOCUS: Subject = {
+  name: 'focus',
+  summary: 'what each element changes about itself when it takes focus',
+  read: readFocusTreatments,
+}
+
+export const SUBJECTS: readonly Subject[] = [FOCUS]
+
+/** Resolves a subject by name, so an unknown one is the caller's to report. */
+export function findSubject(name: string): Subject | undefined {
+  return SUBJECTS.find((subject) => subject.name === name)
+}

package/src/inventory/walk.ts

@@ -0,0 +1,129 @@
+import { chromium } from 'playwright-core'
+import type { Browser } from 'playwright-core'
+import { isBrowserMissing } from '@/browser/engine'
+import { routeUrl } from '@/inventory/config'
+import type { Reading } from '@/inventory/group'
+import type { Subject } from '@/inventory/subjects'
+
+/**
+ * Walks a running application and reads one property off every element a
+ * subject names. Every browser reference the inventory feature adds lives here,
+ * and `src/commands/inventory.ts` reaches it through a dynamic import so no
+ * other command resolves the engine at startup.
+ *
+ * Like `@/demo/drive` and unlike `@/capture/render`, this module ships, because
+ * a command whose whole purpose is running inside someone else's project cannot
+ * stay toolkit-only.
+ */
+
+/**
+ * The reader and the query arrive apart because they come from different
+ * owners. The toolkit ships the reader and the project declares which elements
+ * it runs over, which is what keeps the walk answering to the target rather
+ * than to a fixed selector nobody there chose.
+ */
+export interface WalkOptions {
+  readonly baseUrl: string
+  readonly routes: readonly string[]
+  readonly subject: Subject
+  readonly query: string
+}
+
+/** A route that answered, and the elements read off it. */
+export interface RouteReading {
+  readonly route: string
+  readonly elements: number
+}
+
+export type WalkRefusal =
+  | 'browser-missing'
+  | 'server-unreachable'
+  | 'walk-failed'
+
+export type WalkResult =
+  | {
+      readonly status: 'read'
+      readonly readings: readonly Reading[]
+      readonly routes: readonly RouteReading[]
+      readonly durationMs: number
+    }
+  | {
+      readonly status: 'failed'
+      readonly reason: WalkRefusal
+      readonly message: string
+    }
+
+function failed(reason: WalkRefusal, error: unknown): WalkResult {
+  return {
+    status: 'failed',
+    reason,
+    message: error instanceof Error ? error.message : String(error),
+  }
+}
+
+/**
+ * Separates a server nobody started from a page that failed for its own
+ * reasons. The first is the precondition this command cannot create, and
+ * reporting it as an empty listing would say the site gives no answers when
+ * nothing was ever asked.
+ */
+function isServerUnreachable(error: unknown): boolean {
+  const text = error instanceof Error ? error.message : String(error)
+  return /ERR_CONNECTION_REFUSED|ERR_NAME_NOT_RESOLVED|ERR_CONNECTION_RESET|ERR_EMPTY_RESPONSE/i.test(
+    text,
+  )
+}
+
+export async function walk(options: WalkOptions): Promise<WalkResult> {
+  const started = Date.now()
+
+  let browser: Browser
+  try {
+    browser = await chromium.launch()
+  } catch (error) {
+    return failed(
+      isBrowserMissing(error) ? 'browser-missing' : 'walk-failed',
+      error,
+    )
+  }
+
+  const readings: Reading[] = []
+  const routes: RouteReading[] = []
+
+  try {
+    const page = await browser.newPage()
+
+    for (const route of options.routes) {
+      await page.goto(routeUrl(options.baseUrl, route), {
+        waitUntil: 'domcontentloaded',
+      })
+
+      // Puts the page in keyboard modality before anything is focused, because
+      // a `:focus-visible` ring is the treatment a pointer never reveals and
+      // programmatic focus alone does not match it.
+      await page.keyboard.press('Tab')
+
+      const rows = await page.evaluate(options.subject.read, options.query)
+      for (const row of rows) readings.push({ route, ...row })
+      routes.push({ route, elements: rows.length })
+    }
+  } catch (error) {
+    return failed(
+      isServerUnreachable(error) ? 'server-unreachable' : 'walk-failed',
+      error,
+    )
+  } finally {
+    // The rejection is dropped rather than propagated, because a close that
+    // fails beside a walk that already failed would replace the refusal the
+    // caller was about to receive with a reason about teardown. Nothing the
+    // caller does depends on the browser having closed cleanly.
+    await browser.close().catch(() => undefined)
+  }
+
+  return {
+    status: 'read',
+    readings,
+    routes,
+    durationMs: Date.now() - started,
+  }
+}

package/src/sessions/resolve.ts

@@ -1,4 +1,5 @@
 import { $ } from 'bun'
+import { gitEnv } from '@/git-env'
 import {
   type Confidence,
   liveness,
@@ -67,7 +68,10 @@ export interface Located {
  * that has a worktree and no branch and the second has neither.
  */
 async function locate(cwd: string): Promise<Located> {
-  const top = await $`git -C ${cwd} rev-parse --show-toplevel`.quiet().nothrow()
+  const top = await $`git -C ${cwd} rev-parse --show-toplevel`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
 
   if (top.exitCode !== 0) {
     // git absent and git refusing the directory are both non-zero here. The
@@ -85,7 +89,10 @@ async function locate(cwd: string): Promise<Located> {
 
   const worktree = top.stdout.toString().trim()
   const repository = await repositoryOf(cwd)
-  const head = await $`git -C ${cwd} branch --show-current`.quiet().nothrow()
+  const head = await $`git -C ${cwd} branch --show-current`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
   const branch = head.stdout.toString().trim()
 
   if (head.exitCode !== 0 || branch.length === 0) {
@@ -105,6 +112,7 @@ async function locate(cwd: string): Promise<Located> {
 export async function repositoryOf(cwd: string): Promise<string | null> {
   const dir =
     await $`git -C ${cwd} rev-parse --path-format=absolute --git-common-dir`
+      .env(gitEnv())
       .quiet()
       .nothrow()
 

package/src/worktree.ts

@@ -1,4 +1,5 @@
 import { $ } from 'bun'
+import { gitEnv } from '@/git-env'
 
 /**
  * Resolves the root of the checkout the caller is standing in, which is the
@@ -10,7 +11,10 @@ import { $ } from 'bun'
  * subdirectory would resolve a root holding none of the trees a verb reads.
  */
 export async function currentWorktreeRoot(): Promise<string> {
-  const result = await $`git rev-parse --show-toplevel`.quiet().nothrow()
+  const result = await $`git rev-parse --show-toplevel`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
   if (result.exitCode !== 0) return process.cwd()
 
   return result.stdout.toString().trim() || process.cwd()
@@ -27,7 +31,10 @@ export async function currentWorktreeRoot(): Promise<string> {
  * root in-process is the route a skill body has.
  */
 export async function mainWorktreeRoot(): Promise<string> {
-  const result = await $`git worktree list --porcelain`.quiet().nothrow()
+  const result = await $`git worktree list --porcelain`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
   if (result.exitCode !== 0) return process.cwd()
 
   const line = result.stdout
@@ -52,6 +59,7 @@ export async function listWorktrees(
   cwd: string = process.cwd(),
 ): Promise<readonly WorktreeEntry[]> {
   const result = await $`git -C ${cwd} worktree list --porcelain`
+    .env(gitEnv())
     .quiet()
     .nothrow()
   if (result.exitCode !== 0) return []