---
name: apt:scan
description: "Scan the codebase to build or refresh the .aperant/features/ registry consumed by verify-proof and review"
apt-skill-version: {{APT_VERSION}}
stage: scan
intent: investigate
when_to_use: "The project is brownfield or has grown substantially and the feature registry needs to be built or refreshed against the live codebase."
user_invocable: true
internal: false
spawns_agent: false
agent_name: null
task_context: none
default_execution_mode: auto
execution_modes:
  - auto
  - step
allowed-tools: "Bash, Read, Grep, Glob, Write, Task"
argument-hint: "apt:scan [optional: area to scan, e.g., 'terminals' or 'chat'. Omit for full scan]"
gates: []
---

# Feature Registry Scanner

Maps the codebase into a structured feature registry that other Aperant skills consume.
Each feature area gets its own JSON file listing every sub-feature, its wiring status,
component location, and expected behavior.

## When to Use

- **After `/apt:setup`** on a brownfield project — initial feature discovery
- **After major changes** — refresh the registry when new features are added
- **Before `/apt:verify-proof`** — ensure the feature registry is current
- **Focused scan** — pass an area name to scan only that section (e.g., `terminals`)

## When Not to Use

- Greenfield projects with no code yet
- Trivial changes that don't add new features (use `/apt:execute` post-step instead)

## Output

```
.aperant/features/
  REGISTRY.md           <- index of all feature areas with status
  {area}.json           <- per-area feature inventory (machine-readable)
```

## Design tokens (sibling command — C27)

`apt:scan` owns the **architectural** side of codebase inventory (features, wiring, components). The **design-system** side — colors, spacing, typography, radii, shadows extracted from existing UI code — is a separate pass:

```bash
node packages/framework/bin/apt-tools.mjs design-scan .
# → writes .aperant/design/tokens.json
```

Run it on the same cadence as `apt:scan` (after setup, after major UI changes). Downstream `apt:design` reads `.aperant/design/tokens.json` and injects the tokens into its Stage 1 wireframe so new screens match existing aesthetics by default. See `packages/framework/docs/design-tokens.md` for the output shape and extraction rules.

Conceptually, `apt:scan` + `apt-tools design-scan` together form the brownfield inventory pair:
- `apt:scan` → what the app does (features)
- `design-scan` → how the app looks (tokens)

## Execution

<execution_context>
@packages/framework/workflows/scan-features.md
</execution_context>

<process>
Follow the scan-features workflow from @packages/framework/workflows/scan-features.md.

**Key principles:**
1. Read source code — do not guess what features exist
2. Trace wiring — distinguish connected features from stubbed/dead UI
3. Enumerate exhaustively — every button, slider, toggle, shortcut, dropdown
4. Include component file paths and line numbers for traceability
5. Parallel agents for full scan, single agent for focused scan

The feature registry is a **living document** — other skills update it incrementally.
This skill does the initial creation or full refresh.
</process>

## Config

The feature registry lives in `.aperant/features/` and is committed to the repo.
No additional config needed beyond `.aperant/config.json` (created by `/apt:setup`).

## Integration with Other Skills

| Skill | How it uses the registry |
|-------|--------------------------|
| `/apt:verify-proof` | Reads `{area}.json` to generate exhaustive test cases |
| `/apt:review` | Checks if new components have registry entries |
| `/apt:execute` | Post-step: updates registry when features are added/changed |
| `/apt:plan` | References registry to understand existing feature surface |
| `/apt:design` | Reads the sibling `.aperant/design/tokens.json` (C27) to honor existing aesthetics |
