@design-ai/cli 4.55.0

package/docs/AI-LEARNING.md

@@ -0,0 +1,429 @@
+# AI learning
+
+design-ai supports a local learning profile. This is not model training, fine-tuning, or external telemetry. It is explicit local memory that you choose to include in generated prompts; `check --learn` can derive entries from a local QA report only when you run it.
+
+## Scope
+
+What ships in v4.54:
+
+- `design-ai learn --init` previews starter local learning entries for dogfood use, and `--init --yes` writes them to the selected profile.
+- `design-ai learn --remember ...` stores user or project preferences in a local JSON profile.
+- `design-ai learn --feedback ...` converts outcome feedback into reusable local learning notes.
+- `design-ai check <artifact.md|--stdin> --learn` previews warning/failure QA results as local learning entries, and `--learn --yes` writes them to the selected profile.
+- `design-ai learn --list` shows saved entries, with optional `--category`, `--query`, `--explain`, and `--limit` filters.
+- `design-ai learn --export` prints the Markdown context block used by prompt generation, with the same filters.
+- `design-ai learn --backup` prints a full portable learning-profile backup in JSON mode.
+- `design-ai learn --redact` prints a portable JSON backup with sensitive-looking entry text redacted from the local profile, `--from-file`, or `--stdin`.
+- `design-ai learn --out file` writes JSON result artifacts, `learn --export --out file` writes the Markdown context block, and `learn --curate --report --out file` writes the Markdown curation report, while `--force` controls overwrites.
+- `design-ai learn --verify` validates a portable learning JSON payload without importing it.
+- `design-ai learn --diff --from-file learning.json` compares the active profile against a portable learning JSON payload without importing it, reporting profile-only entries, comparison-only entries, metadata changes, and id conflicts.
+- `design-ai learn --restore --from-file learning-backup.json` previews a full active-profile replacement from a portable backup, and `--restore --yes` applies it only when the source audit has no failures.
+- Confirmed `learn --restore --yes` writes a rollback backup of the previous active profile before replacement; use `--backup-file path` to choose the rollback file.
+- `design-ai learn --restore-backups` lists sibling restore rollback backups for the active profile without mutating the profile.
+- `design-ai learn --restore-backups --prune` previews or applies deleting older sibling restore rollback backups while keeping the newest backups and never mutating the active profile.
+- `design-ai learn --import` merges entries from a JSON learning profile or `learn --export --json` payload.
+- `design-ai learn --audit` inspects profile shape, duplicates, possible sensitive content, and cleanup suggestions without changing the profile.
+- `design-ai learn --audit --fix --dry-run` previews safe cleanup suggestions that can be applied automatically.
+- `design-ai learn --audit --fix --yes` applies only unambiguous safe cleanup suggestions.
+- `design-ai learn --curate` previews archive-first cleanup for duplicate and sensitive learning entries without changing the profile, and includes advisory usage review hints for profile-path mismatch, stale selected ids, and unused active entries when a usage sidecar is available.
+- `design-ai learn --curate --report` emits a Markdown curation report for preview or apply results, and `--out file` writes it as a durable local review artifact.
+- `design-ai learn --curate --yes` moves duplicate/sensitive candidates into a sibling `*.archive.json` file instead of deleting them.
+- `design-ai learn --stats` summarizes profile counts, category/source distribution, recency, and audit status without changing the profile.
+- `design-ai learn --usage` summarizes prompt/pack `--with-learning` usage sidecar events, selected entry counts, unused active entries, and recent usage without changing any files.
+- `design-ai learn --propose-skills` converts repeated check-capture learning signals into preview-only candidate skill instruction deltas without changing `learning.json` or skill files.
+- `design-ai learn --eval-template` generates a runnable learning eval checkpoint JSON from the active profile, optional query, category, and limit.
+- `design-ai learn --eval` validates deterministic learning-selection checkpoints from a JSON file or stdin without changing the profile; add `--strict` to exit non-zero when any checkpoint warns or fails. JSON reports expose checkpoint `generatedAt` plus a sanitized `sourceProfile` summary without raw checkpoint brief or query text.
+- `design-ai workspace` includes the selected learning profile path, entry count, category counts, latest entry, audit status, usage sidecar readiness, eval checkpoint readiness, and canonical repository alignment in a broader read-only dogfood readiness snapshot; add `--learning-usage path` or `--learning-eval path` to include specific artifacts, omit them to auto-detect sibling `learning.usage.json` and `learning-eval.json` files when present, and add `--strict` when warning/failure readiness should fail the command.
+- `design-ai workspace` checks learning usage sidecar readiness when usage metadata is available. If the sidecar points at another profile or references selected entry ids that are no longer present in the active profile, `workspace` emits a warning and suggests `design-ai learn --curate --usage-file ...` so profile audit and usage review are inspected together.
+- When learning curation is recommended, `design-ai workspace` also suggests a companion report artifact command such as `design-ai learn --curate --report --out <learning-file-dir>/learning-curation-report.md`, adding `--usage-file` when usage metadata is part of the readiness warning.
+- `design-ai workspace` checks learning eval checkpoint freshness when metadata is available. If the profile was updated after the checkpoint was generated, the checkpoint came from another profile path, or the source entry count changed, `workspace` emits a warning and suggests regenerating the checkpoint.
+- When a clean learning profile has entries but no checkpoint is available, `design-ai workspace` adds a next-action command for `design-ai learn --eval-template --file <learning.json> --out <learning-file-dir>/learning-eval.json`.
+- `design-ai workspace` automatically detects sibling restore rollback backups such as `learning.restore-backup-*.json`, reports the total/latest backup inventory in JSON as `learningRestoreBackups`, and suggests a preview-first `design-ai learn --restore-backups --prune --keep 5` next action when older backups exceed the default keep count.
+- Workspace next-action commands that include learning profile, usage sidecar, or eval checkpoint paths are shell-quoted, so paths with spaces or apostrophes remain copy/paste safe.
+- Post-publish registry smoke verifies public registry `design-ai workspace --learning-eval learning-eval.json --strict --json` checkpoint summaries, auto-detected learning usage sidecar summaries, public registry `design-ai workspace` workspace restore-backups readiness with restore rollback backup inventory, public registry `design-ai learn --eval-template` checkpoint generation plus generated checkpoint strict validation, public registry JSON `design-ai learn --restore` preview/apply output plus public registry learn restore `--out` file-write confirmation, public registry learn restore rollback backup verification, public registry learn restore `--backup-file` path coverage, public registry `design-ai learn --restore-backups` restore rollback backup inventory coverage, and public registry `design-ai learn --restore-backups --prune` restore rollback backup pruning coverage from the published package path.
+- `design-ai learn --forget ... --yes` removes a single saved entry.
+- `design-ai learn --clear --yes` clears the local profile.
+- `design-ai prompt --with-learning ...` injects learned context into the generated task prompt, ranking entries by current brief relevance before falling back to recency, with optional `--learning-category` and `--learning-limit` scoping plus selection scoring metadata.
+- `design-ai pack --with-learning ...` includes the same brief-relevant learned context in portable prompt packs, with the same optional scoping controls and selection scoring metadata.
+- `prompt --with-learning` and `pack --with-learning` write a local usage sidecar such as `learning.usage.json` with command, route id, selected learning entry ids, selection counts, audit status, and a short brief hash. The sidecar does not store raw brief/query text.
+- Exported and injected learned context carries an audit summary; if the profile has warnings, the generated context includes a notice to run `design-ai learn --audit`.
+
+What does not ship:
+
+- Model fine-tuning.
+- Private model training on user artifacts.
+- External telemetry or background collection outside explicit local CLI runs.
+- Semantic embedding index generation.
+- Background learning from accepted/rejected recommendations without an explicit CLI command.
+
+## Storage
+
+Default path:
+
+```bash
+~/.design-ai/learning.json
+```
+
+Default usage sidecar path:
+
+```bash
+~/.design-ai/learning.usage.json
+```
+
+Override path:
+
+```bash
+DESIGN_AI_LEARNING_FILE=/path/to/learning.json design-ai learn --list
+DESIGN_AI_LEARNING_USAGE_FILE=/path/to/learning.usage.json design-ai prompt "audit checkout UX" --with-learning
+design-ai learn --usage --file /path/to/learning.json --usage-file /path/to/learning.usage.json
+```
+
+The profile and usage sidecar are local to the machine. They are not synced, uploaded, or sent to any provider by this CLI.
+
+For a broader local readiness check that includes git state, learning audit state, and release-script availability, run:
+
+```bash
+design-ai workspace --json
+design-ai workspace --learning-file ./learning.json
+design-ai workspace --learning-file ./learning.json --learning-usage ./learning.usage.json
+design-ai workspace --learning-file ./learning.json --strict
+design-ai workspace --learning-file ./learning.json --learning-usage ./learning.usage.json --learning-eval ./learning-eval.json --strict
+design-ai workspace --strict
+```
+
+This command is read-only. It does not save learning entries, edit the profile, create commits, push branches, or run release scripts.
+
+If the selected learning profile has sibling `learning.usage.json`, `learning-eval.json`, or `learning.restore-backup-*.json` files, `workspace` automatically includes those summaries. Use `--learning-usage path` or `--learning-eval path` only when you want a different sidecar or checkpoint.
+
+When usage metadata is available, `workspace` compares it against the selected profile. A usage sidecar becomes a readiness warning when its `profileFile` points at another profile or when its selected entry ids no longer exist in the active profile, and the next actions point to usage-aware curation plus a companion curation Markdown report rather than a separate usage-only report.
+
+When checkpoint metadata is available, `workspace` also compares it against the selected profile. A passing checkpoint still becomes a readiness warning when the profile `updatedAt` is newer than checkpoint `generatedAt`, when `sourceProfile.file` does not match the active profile path, or when the recorded source entry count differs from the active profile count.
+
+If the selected profile, usage sidecar, report output, or checkpoint path includes spaces or shell-sensitive characters, the suggested `learn --curate --usage-file`, `learn --curate --report --out`, `learn --usage`, `learn --propose-skills`, `learn --eval-template`, and `learn --eval --from-file` commands quote the path in the next action output.
+
+If the selected learning profile already contains entries and passes audit, `workspace` suggests an eval-template bootstrap command until a sibling or explicit checkpoint is available:
+
+```bash
+design-ai learn --eval-template --file ./learning.json --out ./learning-eval.json
+design-ai workspace --learning-file ./learning.json --strict
+```
+
+For a durable local AI/agent development handoff, save the read-only signal registry as Markdown:
+
+```bash
+design-ai learn --signals --from-file . --report --out learning-signals.md
+```
+
+The report includes learning audit state, usage sidecar counts, eval signal files, check-capture summaries, workspace readiness, deterministic agent development backlog actions, recommendations, and privacy boundaries. JSON readiness output also includes `requiredCheckIds`, `optionalCheckIds`, `checkStatusById`, and `checkRequiredById` so local automation can branch on a specific readiness check without scanning the full `checks` array. It does not mutate `learning.json`, usage sidecars, eval files, skill files, or target repositories.
+
+If sibling restore rollback backups are present, `workspace` remains read-only and only reports the inventory. When more than five backups exist, the next action points to a dry-run-safe prune command:
+
+```bash
+design-ai learn --restore-backups --file ./learning.json --prune --keep 5
+```
+
+## Usage
+
+Bootstrap a starter profile:
+
+```bash
+design-ai learn --init
+design-ai learn --init --yes
+design-ai learn --init --yes --json
+```
+
+`learn --init` is preview-first and does not mutate the profile. Add `--yes` to save deterministic starter entries for recommendation style, implementation workflow, accessibility, Korean UX, brand language, and local data boundaries. Existing `category + normalized text` duplicates are skipped and reported, so re-running the command is safe.
+
+Remember a preference:
+
+```bash
+design-ai learn --remember "Prefer dense Korean product UI with restrained enterprise styling" --category korean
+```
+
+Record outcome feedback:
+
+```bash
+design-ai learn --feedback "Keep audit findings short and evidence-led" --outcome keep
+design-ai learn --feedback "Avoid decorative marketing language in enterprise dashboards" --outcome avoid --category brand
+design-ai learn --feedback --from-file feedback.md --outcome improve --category workflow
+cat feedback.md | design-ai learn --feedback --stdin --outcome avoid --category brand
+```
+
+Feedback is explicit local memory. `--outcome keep` stores a "repeat this" instruction, `--outcome improve` stores an "improve future outputs by..." instruction, and `--outcome avoid` stores an "avoid this" instruction. The default feedback category is `workflow`; use `--category` when feedback belongs to brand, accessibility, Korean-market behavior, or another scoped area. Use `--from-file` or `--stdin` when the reviewed-output note is too long or already saved in another tool.
+
+Capture artifact QA feedback:
+
+```bash
+design-ai check output.md --learn
+design-ai check output.md --learn --yes
+cat output.md | design-ai check --stdin --learn --yes --learning-file ./learning.json --json
+```
+
+`check --learn` is a preview and does not mutate the profile. Add `--yes` to save only warning/failure check results. The capture keeps the existing learning entry shape (`id`, `category`, `text`, `source`, `createdAt`), records source as `check:<routeId>` or `check:artifact`, maps keyboard/screen-reader findings to `accessibility`, Korean-context findings to `korean`, and all remaining check findings to `workflow`. Duplicate category+normalized text pairs are skipped and reported.
+
+List saved preferences:
+
+```bash
+design-ai learn --list
+design-ai learn --list --json
+design-ai learn --list --category korean --limit 5
+design-ai learn --list --query "keyboard accessibility" --explain --json
+```
+
+Export the learned context block:
+
+```bash
+design-ai learn --export
+design-ai learn --export --category accessibility --limit 3
+design-ai learn --export --query "pricing page" --limit 3
+design-ai learn --export --out learned-context.md
+```
+
+`--query` filters list/export output to entries whose category or text matches the query tokens. Unlike prompt/pack learning injection, query-filtered list/export does not fill remaining limit slots with recency fallback entries, so it is safe for profile inspection. Add `--explain` to `learn --list` when you need the selection score, matched tokens, and reason for each listed entry; JSON output includes the same selection metadata shape used by prompt/pack learning context. The exported block includes profile audit metadata in JSON mode. Human Markdown stays compact when the profile passes audit, and includes a warning notice when the profile has audit warnings. `--out` writes the Markdown block for `--export`, and refuses to overwrite an existing file unless `--force` is provided.
+
+Back up the full local profile:
+
+```bash
+design-ai learn --backup --json --out learning-backup.json
+```
+
+Backup JSON includes all normalized entries, the source profile path, profile metadata, an `exportedAt` timestamp, and the current audit summary. The payload keeps an `entries` array, so it can be reviewed and then restored or imported on another machine with `design-ai learn --restore` or `design-ai learn --import`. `--out` uses the same safe file-write rules as `prompt` and `pack`: existing files are rejected unless you add `--force`.
+
+Create a redacted portable profile before sharing:
+
+```bash
+design-ai learn --redact --json --out learning-redacted.json
+design-ai learn --redact --from-file learning-backup.json --json --out learning-redacted.json --force
+cat learning-backup.json | design-ai learn --redact --stdin --json --out learning-redacted.json --force
+```
+
+Redacted JSON keeps the same importable `entries` shape as a backup, but replaces conservative sensitive-content matches with `[REDACTED:<code>]` markers and includes `redactions`, `sourceAuditSummary`, and post-redaction `auditSummary` fields. It is read-only and does not change the source profile or source portable payload.
+
+Verify a portable learning payload before importing:
+
+```bash
+design-ai learn --verify --from-file learning-backup.json
+cat learning-backup.json | design-ai learn --verify --stdin --json
+```
+
+Verify mode parses the same `entries` payload accepted by import, normalizes imported entry metadata, and reports audit warnings such as duplicate ids or sensitive-looking text. It never reads or writes the target local profile.
+
+Compare a portable learning payload against the active profile:
+
+```bash
+design-ai learn --diff --from-file learning-backup.json
+design-ai learn --diff --from-file learning-backup.json --json --out learning-diff.json
+cat learning-backup.json | design-ai learn --diff --stdin --json
+```
+
+Diff mode is read-only. It compares the active profile with a portable profile by category plus normalized text, then reports profile-only entries, comparison-only entries, metadata changes for matching notes, and id conflicts where the same id points at different learning text.
+
+Restore the active profile from a portable backup:
+
+```bash
+design-ai learn --backup --json --out learning-backup.json
+design-ai learn --verify --from-file learning-backup.json
+design-ai learn --diff --from-file learning-backup.json --json
+design-ai learn --restore --from-file learning-backup.json
+design-ai learn --restore --from-file learning-backup.json --yes --json
+design-ai learn --restore --from-file learning-backup.json --yes --backup-file learning-before-restore.json
+design-ai learn --restore-backups
+design-ai learn --restore-backups --json --out restore-backups.json
+design-ai learn --restore-backups --prune --keep 5
+design-ai learn --restore-backups --prune --keep 5 --yes
+cat learning-backup.json | design-ai learn --restore --stdin --yes
+```
+
+Restore is preview-first and replaces the active profile only when `--yes` is present. It requires `--from-file` or `--stdin`, rejects `--dry-run` combined with `--yes`, and refuses to apply a source payload whose audit has failures. Confirmed apply writes the previous active profile to a rollback backup before the replacement. The default rollback path is a sibling timestamped file such as `learning.restore-backup-20260602T010203000Z.json`; pass `--backup-file path` to choose a specific file. Existing explicit rollback files require `--force`, and the rollback path cannot be the active profile or restore source. JSON output reports the target file, dry-run/apply state, restorable state, rollback `backupFile`, `backupCreated`, `backupEntryCount`, rollback preview command, previous/restored counts, removed/added counts, same-text count, metadata changes, id conflicts, audit summary, diff details, and privacy metadata. Use restore when the backup should become the complete active profile; use import when you only want to merge new entries while keeping the existing profile.
+
+`learn --restore-backups` is read-only. It searches for sibling files matching `learning.restore-backup-*.json`, reports the latest backups first, audits each backup file, and prints a restore dry-run preview command for each candidate. Use this when you need to find the automatic rollback file from a previous confirmed restore before deciding whether to preview or apply a rollback.
+
+`learn --restore-backups --prune` is preview-first. It keeps the newest rollback backups, reports older backup files that would be deleted, and deletes those older backup files only when `--yes` is present. It never changes the active `learning.json` profile.
+
+Import a portable learning profile:
+
+```bash
+design-ai learn --backup --json --out learning-backup.json
+design-ai learn --redact --json --out learning-redacted.json
+design-ai learn --redact --from-file learning-backup.json --json --out learning-redacted.json --force
+design-ai learn --verify --from-file learning-backup.json
+design-ai learn --diff --from-file learning-backup.json --json
+design-ai learn --import --from-file learning-backup.json --dry-run
+cat learning-backup.json | design-ai learn --import --stdin --yes
+```
+
+Import accepts JSON objects with an `entries` array, including full local profile files and `learn --export --json` output. `--dry-run` previews added and skipped entries without mutating the target profile. Confirmed import requires `--yes`, skips duplicate category+text pairs, preserves imported timestamps when valid, marks imported sources with `import:`, and remints ids only when an imported id conflicts with an existing entry.
+
+Audit the local profile before using it in prompts:
+
+```bash
+design-ai learn --audit
+design-ai learn --audit --json
+design-ai learn --audit --fix --dry-run
+design-ai learn --audit --fix --yes
+design-ai learn --curate
+design-ai learn --curate --usage-file ./learning.usage.json
+design-ai learn --curate --report --out learning-curation-report.md
+design-ai learn --curate --yes --json
+```
+
+The plain audit is advisory and non-mutating. It reports invalid JSON/profile shape failures plus warnings for duplicate entries, missing timestamps, long notes, and conservative sensitive-content patterns such as secret-like assignments, private key blocks, email addresses, and Korean mobile phone numbers. JSON output includes `suggestions`; human output adds a Suggested cleanup section with safe `design-ai learn --file ... --forget ... --yes` commands only when id-based deletion is unambiguous.
+
+`--audit --fix --dry-run` turns those safe suggestions into a cleanup plan without changing the file. `--audit --fix --yes` removes only entries that have stable, unambiguous ids and skips anything that still needs manual review, such as invalid JSON, duplicate ids, malformed entries, or warnings without a safe target.
+
+`--curate` is the safer Hermes-inspired path for normal profile maintenance. It previews curation proposals by default, classifies duplicate text and conservative sensitive-content warnings as archive candidates, and leaves timestamp, long-note, malformed-entry, duplicate-id, or profile-level failures for manual review. When a default or explicit `--usage-file` sidecar is available, the same preview adds a usage review section for sidecars recorded against a different profile path, stale selected ids, and active entries that have not appeared in recorded prompt/pack usage. Usage review is advisory only: `autoArchive` stays `false`, and unused or mismatched usage signals never archive entries by themselves. Add `--report` when you need a Markdown audit trail with profile/archive paths, before/after summaries, archive candidates, manual review items, usage review, privacy notes, and next steps; `--curate --report --out file` writes that report without requiring `--json`. Confirmed `--curate --yes` rewrites the active `learning.json` with duplicate/sensitive archive candidates removed and appends their full entries plus `archivedAt`, `archiveReason`, `issueCodes`, and `originalFile` metadata to a sibling archive file such as `learning.archive.json`. No archive file is written during preview.
+
+Summarize profile health and recency:
+
+```bash
+design-ai learn --stats
+design-ai learn --stats --json
+```
+
+Stats mode is also read-only. It is a compact overview for deciding whether to inspect, filter, or clean up the profile before using `--with-learning`.
+
+Summarize usage sidecar activity:
+
+```bash
+design-ai learn --usage
+design-ai learn --usage --json
+design-ai learn --usage --limit 5 --usage-file ./learning.usage.json
+```
+
+Usage mode is read-only. It reports event count, command/route/category distribution, entry ids selected by `prompt` and `pack`, active profile entries that have not been used yet, stale selected ids no longer present in the active profile, and recent events. It preserves the privacy boundary from the sidecar: selected entry ids and short brief hashes are shown, but raw prompt or query text is not stored or reported.
+
+Preview skill evolution proposals:
+
+```bash
+design-ai learn --propose-skills
+design-ai learn --propose-skills --from-file . --json
+design-ai learn --propose-skills --from-file . --min-evidence 3 --json
+design-ai learn --propose-skills --from-file . --review-file skill-proposals.review.json --strict --json
+design-ai learn --propose-skills --from-file . --review-template --out skill-proposals.review.json
+design-ai learn --propose-skills --from-file . --patch --out skill-proposals.patch
+design-ai learn --propose-skills --from-file route-eval-report.json --usage-file ./learning.usage.json --json --out skill-proposals.json
+```
+
+Skill proposal mode is read-only. It scans active learning entries whose `source` starts with `check:`, groups repeated check-capture signals by candidate skill and category, and emits proposal records with `candidateSkillPath`, `evidenceSources`, `proposedInstructionDelta`, `verificationCommand`, and `riskLevel`. Single-entry groups are reported as skipped until enough repeated evidence exists. Use `--min-evidence N` when a project needs stricter review before skill edits, or a lower local threshold for early dogfood review. Use `--review-template --out skill-proposals.review.json` to scaffold a JSON decision file for current unresolved proposals; generated decisions default to `deferred` so the gate stays pending until an operator deliberately changes a decision to `applied` or `rejected`. Use `--review-file skill-proposals.review.json` to join manual decisions without changing that file; proposal decisions with `status: "applied"` or `status: "rejected"` clear the proposal review gate, while `accepted` and `deferred` remain pending. Use `--patch --out skill-proposals.patch` when an operator wants a unified diff handoff for unresolved proposals before editing any skill file. The command is deliberately preview-only: `--yes` is rejected, `learning.json` is not changed, `skills/*/SKILL.md` is not edited, the review file is not changed unless the operator explicitly writes a separate `--review-template --out` artifact, and no external AI API is called.
+
+Minimal review file:
+
+```json
+{
+  "version": 1,
+  "decisions": [
+    {
+      "proposalId": "skill-proposal-website-improvement-abc123",
+      "status": "applied",
+      "reviewedAt": "2026-06-11T00:00:00.000Z",
+      "reviewer": "local-operator",
+      "note": "Instruction delta manually applied and verified."
+    }
+  ]
+}
+```
+
+Evaluate learning-selection checkpoints:
+
+```bash
+design-ai learn --eval-template --query "Spec a Button component API with keyboard accessibility" --category accessibility --out learning-eval.json
+cat > learning-eval.json <<'JSON'
+{
+  "version": 1,
+  "cases": [
+    {
+      "id": "button-accessibility",
+      "routeId": "component-spec",
+      "brief": "Spec a Button component API with keyboard accessibility",
+      "category": "accessibility",
+      "limit": 1,
+      "expectedSelectedIds": ["learn-relevant"],
+      "avoidedSelectedIds": ["learn-brand"],
+      "minMatchedCount": 1,
+      "requireNoFallback": true
+    }
+  ]
+}
+JSON
+design-ai learn --eval --from-file learning-eval.json --strict --json
+cat learning-eval.json | design-ai learn --eval --stdin --category accessibility --limit 1
+design-ai learn --eval --from-file learning-eval.json --json --out learning-eval-report.json
+```
+
+`learn --eval-template` is read-only and writes a checkpoint file that can be passed directly to `learn --eval`; checkpoint templates intentionally store raw `brief` text so they can be re-run locally, so review them before sharing. Eval mode is also read-only. It compares checkpoint cases against the same brief-relevance selection used by `prompt --with-learning` and `pack --with-learning`, then reports expected selected ids, avoided selected ids, minimum matched counts, fallback policy failures, and per-case status. JSON and human eval reports expose a short `briefHash`, selected entry ids, counts, and issues; they do not expose raw brief/query text or matched tokens. `--out` writes only the eval report artifact and follows the normal overwrite protection unless `--force` is provided.
+Add `--strict` when the eval report should act as a local CI or release gate: the report is printed or written first, then the command exits non-zero if any case warns or fails.
+
+Remove one saved entry:
+
+```bash
+design-ai learn --forget learn-abc123def0 --yes
+design-ai learn --forget 2 --yes
+```
+
+Clear every saved entry:
+
+```bash
+design-ai learn --clear --yes
+```
+
+Use learned context in a prompt:
+
+```bash
+design-ai prompt "Audit this checkout UX" --with-learning
+design-ai prompt "Audit this checkout UX" --with-learning --learning-category korean --learning-limit 5
+```
+
+When `--with-learning` is used, generated prompt plans include the same audit summary as `learn --export --json`. The selected entries are ranked against the prompt brief first, then recency is used for ties or unmatched fallback entries. JSON output includes `selection.selected[]` with each selected entry's `id`, `category`, relevance `score`, `matchedTokens`, and `reason` (`brief-match`, `recency-fallback`, or `recency`). Prompt and pack JSON also include `learningUsage`, and the CLI writes a local sidecar event that records selected entry ids and a short brief hash, not raw brief text. The learned-context block includes a compact selection note, and if the local profile has audit warnings, it tells the receiving agent to run `design-ai learn --audit` before relying on that context.
+
+Use learned context in a prompt pack:
+
+```bash
+design-ai pack "Spec a pricing page for Korean SaaS" --with-learning --max-bytes 80000
+design-ai pack "Spec a pricing page for Korean SaaS" --with-learning --learning-category brand --learning-limit 3 --max-bytes 80000
+```
+
+## Categories
+
+Use categories to make learned context scannable:
+
+| Category | Use for |
+|---|---|
+| `preference` | General design taste or output preference |
+| `brand` | Brand voice, visual language, tone |
+| `workflow` | Team process, handoff, review norms |
+| `constraint` | Business, legal, product, or platform constraints |
+| `accessibility` | Accessibility preferences that exceed the baseline |
+| `korean` | Korean market, language, typography, or platform conventions |
+| `other` | Anything that does not fit the above |
+
+## Safety rules
+
+Learning entries are treated as preferences, not absolute instructions. They must not override:
+
+- Explicit task instructions.
+- Accessibility requirements.
+- Privacy constraints.
+- Legal or policy constraints.
+- Checked knowledge files and route playbooks.
+
+Use `--with-learning` only when saved context should influence the current task. The CLI prioritizes entries whose category/text match the current brief, then falls back to recent entries when the limit still has room. Inspect `learningContext.selection` in `--json` output when you need to confirm whether an entry was selected by brief match or recency fallback. Add `--learning-category <kind>` and `--learning-limit <N>` when only one category or a small subset should influence the prompt. Use `design-ai learn --list --query <text> --explain` or `design-ai learn --export --query <text>` when you want to inspect matching local preferences without recency fallback.
+
+Run `design-ai learn --audit` before exporting or injecting a profile that may contain copied project notes, credentials, contact details, or stale entries. Follow the Suggested cleanup section when it recommends removal; rewrite and re-add entries when the issue is sensitive content or an overlong note that still contains useful preference signal.
+
+Use `design-ai learn --stats` when you need a quick read on profile size, category distribution, source distribution, latest entry, and audit status before deciding whether to run a detailed audit.
+
+Use `design-ai learn --feedback` only for durable preferences you want future prompts to see. Do not store one-off task corrections, private project facts, credentials, contact details, or unresolved critique as feedback entries.
+
+Use `design-ai learn --verify --from-file` before reviewing or applying a profile from another machine or repository. It confirms the payload is importable without touching your current local profile.
+
+Use `design-ai learn --diff --from-file` after verification when you need to understand what would be new, missing, or metadata-changed before deciding whether to import or restore a portable profile.
+
+Use `design-ai learn --redact --json --out learning-redacted.json` before sending a local learning profile to another person, repository, or support channel. If you already have a portable backup artifact, use `design-ai learn --redact --from-file learning-backup.json --json --out learning-redacted.json --force` or pipe it through `design-ai learn --redact --stdin --json --out learning-redacted.json --force` so the original artifact remains unchanged. Review the resulting `redactions` list and then run `design-ai learn --verify --from-file learning-redacted.json` if the redacted profile will be imported elsewhere.
+
+Use `design-ai learn --import --dry-run` before applying a profile from another machine or repository. Audit the source first when it may include copied project notes, credentials, contact details, or stale entries.
+
+Use `design-ai learn --backup --json --out learning-backup.json` before major cleanup or machine migration when you need a complete local copy. Unlike `learn --export`, backup is not limited to the default prompt-context subset, and `--out` avoids accidental shell redirection overwrites unless `--force` is explicit.
+
+Treat any learned-context audit warning as a review prompt, not as permission to include risky data. Remove, rewrite, or scope entries before using `--with-learning` when audit warnings are not expected. Use `--audit --fix --dry-run` first when you want to see which entries can be cleaned automatically.
+
+Deletion actions and confirmed import require `--yes` because they mutate the local profile. Use `--list` first when you need the exact id or list number.

package/docs/AIDER-INTEGRATION.md

@@ -0,0 +1,224 @@
+# Aider integration
+
+How to use design-ai with **Aider** (terminal-based AI pair programmer, supports Claude/GPT models).
+
+> **Looking for a worked example?** See [`docs/integrations/aider-walkthrough.md`](integrations/aider-walkthrough.md) — concrete sessions for component implementation, refactoring, design system bootstrap, and audit-then-fix workflows. Includes architect-mode, auto-test, and bash alias patterns.
+
+## Quickstart
+
+Aider's `--read` flag adds files as read-only context. Pass design-ai entry docs at startup:
+
+```bash
+cd /path/to/your/project
+
+aider \
+  --read /path/to/design-ai/AGENTS.md \
+  --read /path/to/design-ai/knowledge/PRINCIPLES.md \
+  --message "Generate a fintech color palette for a Korean B2C app"
+```
+
+Aider primes itself with the design-ai context, then handles the task in your project.
+
+## Configuration via `.aider.conf.yml`
+
+For repeated use, configure at the project level:
+
+```yaml
+# .aider.conf.yml — in your consuming project's root
+
+read:
+  - /path/to/design-ai/AGENTS.md
+  - /path/to/design-ai/knowledge/PRINCIPLES.md
+  - /path/to/design-ai/knowledge/a11y/contrast.md
+  - /path/to/design-ai/knowledge/a11y/keyboard-and-focus.md
+  - /path/to/design-ai/knowledge/i18n/korean-typography.md       # if Korean
+  - /path/to/design-ai/knowledge/i18n/korean-product-conventions.md
+
+# Read-only references — Aider won't try to edit them
+auto-commits: false              # safer for design-ai docs
+edit-format: diff                # cleaner for design system files
+
+# Map to your model preference
+model: claude-3-5-sonnet
+```
+
+Now `aider` in this project auto-loads design-ai context.
+
+## Per-task context loading
+
+For specific tasks, pair the entry docs with the relevant skill playbook:
+
+```bash
+# Color palette
+aider \
+  --read /path/to/design-ai/AGENTS.md \
+  --read /path/to/design-ai/knowledge/PRINCIPLES.md \
+  --read /path/to/design-ai/skills/color-palette/PLAYBOOK.md \
+  --read /path/to/design-ai/knowledge/colors/color-theory.md \
+  --read /path/to/design-ai/knowledge/colors/palettes-by-product-type.md \
+  --message "Apply color-palette skill to: B2C fintech, Korean, teal seed"
+
+# Component spec
+aider \
+  --read /path/to/design-ai/AGENTS.md \
+  --read /path/to/design-ai/skills/component-spec-writer/PLAYBOOK.md \
+  --read /path/to/design-ai/knowledge/components/INDEX.md \
+  --read /path/to/design-ai/examples/component-button.md \
+  --message "Spec a custom RadioCard component"
+
+# UX audit
+aider \
+  --read /path/to/design-ai/AGENTS.md \
+  --read /path/to/design-ai/skills/ux-audit/PLAYBOOK.md \
+  --read /path/to/design-ai/knowledge/patterns/ux-guidelines.md \
+  --message "Audit src/screens/Checkout.tsx"
+```
+
+Aider opens with full context, then operates on your project files.
+
+## Per-skill scripts
+
+Save shell aliases for common tasks:
+
+```bash
+# In ~/.bashrc or ~/.zshrc
+
+DESIGN_AI=/path/to/design-ai
+
+# Palette generation
+alias design-palette='aider \
+  --read $DESIGN_AI/AGENTS.md \
+  --read $DESIGN_AI/knowledge/PRINCIPLES.md \
+  --read $DESIGN_AI/skills/color-palette/PLAYBOOK.md \
+  --read $DESIGN_AI/knowledge/colors/color-theory.md'
+
+# Component spec
+alias design-spec='aider \
+  --read $DESIGN_AI/AGENTS.md \
+  --read $DESIGN_AI/skills/component-spec-writer/PLAYBOOK.md \
+  --read $DESIGN_AI/knowledge/components/INDEX.md'
+
+# UX audit
+alias design-audit='aider \
+  --read $DESIGN_AI/AGENTS.md \
+  --read $DESIGN_AI/skills/ux-audit/PLAYBOOK.md \
+  --read $DESIGN_AI/knowledge/patterns/ux-guidelines.md \
+  --read $DESIGN_AI/knowledge/a11y/contrast.md'
+
+# QA audit
+alias design-qa='aider \
+  --read $DESIGN_AI/AGENTS.md \
+  --read $DESIGN_AI/skills/design-system-qa/PLAYBOOK.md \
+  --read $DESIGN_AI/knowledge/patterns/design-system-qa.md'
+```
+
+Then:
+
+```bash
+cd my-project
+design-palette "fintech B2C, teal seed, Korean"
+```
+
+## Aider-specific features
+
+### `/read` and `/drop` mid-conversation
+
+Aider lets you add/remove read-only files mid-conversation:
+
+```
+> /read /path/to/design-ai/knowledge/i18n/korean-payments.md
+
+OK, now I'll consider Korean payment patterns in suggestions.
+
+> Apply that to checkout flow
+
+[Aider produces output citing the Korean payment file]
+
+> /drop /path/to/design-ai/knowledge/i18n/korean-payments.md
+```
+
+This keeps the context lean — only load what you need for the current step.
+
+### Repo map
+
+Aider auto-builds a repo map of your project. To include design-ai in the map, either symlink it as a folder OR keep it separate and use `--read` for explicit loading.
+
+For most workflows: keep design-ai separate; load specific files via `--read` per task.
+
+### Model routing
+
+Aider supports multiple models per task:
+
+```bash
+aider --model claude-3-5-sonnet     # heavy design tasks
+aider --model haiku                  # quick edits
+```
+
+For design-ai tasks: prefer Sonnet/Opus. Haiku may miss the citation discipline.
+
+## Aider workflow patterns
+
+### Pattern A: Apply skill + edit code
+
+```bash
+cd my-project
+
+aider \
+  --read /path/to/design-ai/AGENTS.md \
+  --read /path/to/design-ai/skills/component-spec-writer/PLAYBOOK.md \
+  --read /path/to/design-ai/examples/component-button.md \
+  src/components/Button/Button.tsx
+
+# Now in Aider:
+> "Refactor src/components/Button/Button.tsx to match the spec.
+>  Include all variants and states from the spec."
+```
+
+Aider edits Button.tsx per the spec, with design-ai's discipline.
+
+### Pattern B: Generate spec, then implement
+
+```bash
+# Step 1: Generate the spec
+aider \
+  --read /path/to/design-ai/AGENTS.md \
+  --read /path/to/design-ai/skills/component-spec-writer/PLAYBOOK.md \
+  --message "Spec a Toast component for our React + Tailwind project. Save to docs/component-toast.md."
+
+# Step 2: Implement against the spec
+aider \
+  --read docs/component-toast.md \
+  --message "Implement Toast in src/components/Toast/Toast.tsx per the spec."
+```
+
+Two passes; spec is the contract between them.
+
+### Pattern C: Apply iterate command
+
+```bash
+aider \
+  --read /path/to/design-ai/commands/iterate.md \
+  --read examples/palette-saas-violet.md \
+  --message "Apply iterate to palette-saas-violet with critique:
+  Primary feels too saturated. Add a tertiary text color. Increase
+  focus-ring contrast on light bg."
+```
+
+Aider applies the change + outputs a changelog.
+
+## Common pitfalls
+
+| Pitfall | Fix |
+| --- | --- |
+| Aider tries to edit design-ai files | Load with `--read` (read-only). Aider won't suggest edits to read-only files. |
+| Aider's repo map crowds context | Disable repo map for design-tasks: `--map-tokens 0`. |
+| Aider invents APIs without checking refs/ | Pass relevant `examples/component-*.md` and `refs/` paths explicitly. |
+| Aider's diff output is hard to read for design specs | Use `--edit-format whole` for design-ai output (full file replacement is clearer for spec docs). |
+
+## Cross-reference
+
+- [`docs/USING.md`](USING.md) — multi-agent setup overview
+- [`docs/CODEX-INTEGRATION.md`](CODEX-INTEGRATION.md) — Codex CLI deep-dive
+- [`docs/CURSOR-INTEGRATION.md`](CURSOR-INTEGRATION.md) — Cursor IDE setup
+- [`AGENTS.md`](../AGENTS.md) — universal agent instructions
+- [`knowledge/PRINCIPLES.md`](../knowledge/PRINCIPLES.md) — agent priming