@event4u/agent-config 9.7.0 → 9.9.0

package/docs/guides/frontend-design-corpus-refresh.md

@@ -1,83 +0,0 @@
-# Corpus refresh runbook — trigger-eval recording (ADR-061 §6 DoD)
-
-How to refresh a corpus-backed skill (`design-intelligence`, and any future
-SHA-pinned corpus) and keep its trigger-eval provenance current. This is the
-**corpus-refresh Definition of Done**: a refresh that bumps the upstream SHA or
-edits the routing description is not done until a live trigger-eval has been
-re-run and recorded against the new pin.
-
-> **Scope.** Applies to a skill whose `data/manifest.json` has an
-> `upstream` block with a real `sha`. Original-authored corpora (`upstream:
-> null`, e.g. `brand`) have no SHA to pin an eval to and are out of scope —
-> `lint_eval_freshness.py` skips them.
-
-## When a refresh fires
-
-- The upstream SHA is bumped (new corpus content adopted), OR
-- The skill's `description` (its routing trigger surface) is edited, OR
-- The quarterly refresh cadence in the manifest comes due.
-
-Any of these can change which queries the description fires on, so the recorded
-recall/precision must be re-measured.
-
-## The refresh steps
-
-1. **Bump the pin / edit the corpus** in `src/skills/<skill>/data/` and update
-   `upstream.sha` + `upstream.last_checked` in the manifest.
-
-2. **Run the live trigger-eval** (token spend — interactive, gated):
-
-   ```bash
-   
-   task install-anthropic-key  # once: install ~/.event4u/agent-config/anthropic.key
-   ./scripts-run src/scripts/skill_trigger_eval \
-     --skill <skill> --output /tmp/<skill>-eval.json
-   ```
-
-   The runner enforces a tty + an explicit `yes` at the cost preview. It writes
-   the `EvalResult` JSON (router, model, metrics) to `--output`.
-
-3. **Record the result into the manifest:**
-
-   ```bash
-   agent-config eval:record \
-     --eval-json /tmp/<skill>-eval.json \
-     --manifest src/skills/<skill>/data/manifest.json
-   ```
-
-   This stamps `upstream.last_eval` with the measured precision/recall, the
-   `sha_at_eval` (= the current `upstream.sha`), the domain-specific floor, and
-   `passed`. Exit codes: `0` pass · `1` recorded-but-floor-missed · `2`
-   integrity error (nothing written). A `--dry-run` / MockRouter result is
-   refused unless `--allow-mock` (plumbing only) — a mock number is never
-   provenance.
-
-4. **Re-condense + commit** the manifest change through the normal `src/` →
-   `/condense` flow.
-
-## Definition of Done
-
-A corpus-refresh PR does **not** merge unless, for every in-scope skill it
-touches:
-
-- `upstream.last_eval.passed: true`, AND
-- `upstream.last_eval.sha_at_eval == upstream.sha`.
-
-`src/scripts/lint_eval_freshness.py` (deterministic, no token spend) enforces
-this. It is run standalone today (`task lint-eval-freshness`); it moves into the
-blocking `task ci-fast` aggregate once the in-scope corpora carry a recorded
-`last_eval` (the one-time live backfill below).
-
-## One-time backfill
-
-Every already-shipped, SHA-pinned corpus skill needs its first recording. Run
-steps 2–3 once per skill — `design-intelligence` first, then any other
-SHA-pinned corpus that ships `evals/triggers.json`. Because step 2 is a live,
-spend-bearing run, do the backfill as a deliberate, confirmed pass — not
-autonomously.
-
-## See also
-
-- [`recordTriggerEval.ts`](../../src/cli/commands/recordTriggerEval.ts) — the `eval:record` implementation + domain-specific floors.
-- [`lint_eval_freshness.py`](../../src/scripts/lint_eval_freshness.py) — the deterministic freshness gate.
-- [`corpus-grounding`](../../src/skills/corpus-grounding/SKILL.md) + [ADR-061](../decisions/ADR-061-corpus-grounding-layer.md) §6 — the provenance discipline this DoD enforces.

package/docs/guides/local-analytics.md

@@ -1,125 +0,0 @@
-# Local analytics — a 3-minute walkthrough
-
-> Phase 7 of [`road-to-employee-product-and-external-proof`](../../agents/roadmaps/archive/road-to-employee-product-and-external-proof.md).
-> Contract: [`docs/contracts/local-analytics.md`](../contracts/local-analytics.md).
-
-## What this is
-
-A **local-only** event log of your workspace activity. The package never
-POSTs these records anywhere. Storage is a single append-only JSONL file
-under your home directory; pruning is a 90-day rolling window.
-
-If you want to know *"which prompts do I actually run on Tuesday
-mornings?"* — this is the file that knows. If you don't want that
-question answered, flip one flag and the file never opens.
-
-## Where it lives
-
-```
-~/.event4u/agent-config/workspace/analytics/
-├── events.jsonl          # one workspace_event/v0 record per line
-└── retention.lock        # presence = a prune pass is running
-```
-
-One event per line. Schema is `workspace_event/v0` (matches the
-3.1.0 telemetry SDK vocabulary, but the transports never touch each
-other — the SDK is the undeployed Worker surface, this is your disk).
-
-## What's collected
-
-Closed event set (rejected if not on the list):
-
-| Event | When |
-|---|---|
-| `launcher.opened`         | Workspace tab opens. |
-| `launcher.task_picked`    | User clicks a task in the launcher. |
-| `launcher.task_launched`  | Host agent receives the rendered prompt. |
-| `session.started` / `session.host_turn` / `session.completed` | Conversation lifecycle. |
-| `document.created` / `document.edited` / `document.exported` | Phase 5 document workflows. |
-| `explain.opened` / `explain.mode_toggled` / `why.invoked` | Phase 6 explain mode. |
-| `knowledge.queried` / `knowledge.source_clicked` | Phase 2 knowledge pane interactions. |
-
-Each record carries a UTC timestamp, the schema version, and a tiny
-`data` dict (role, task, host_tier, duration_ms — never prompt or
-response bodies).
-
-## How to read it
-
-```bash
-# Render the last 30 days as markdown
-./agent-config analytics show
-
-# Last 24 h, JSON
-./agent-config analytics show \
-    --window 24h --format json
-
-# Filter to one role
-./agent-config analytics show \
-    --role tradesperson --format csv
-```
-
-Output shape (markdown):
-
-```
-# Workspace analytics — last 30d
-
-## Top prompts
-
-- `tradesperson` · `estimate` — 12
-- `content-creator` · `script-video` — 7
-- `consultant` · `weekly-memo` — 4
-
-## Launcher → completion rate per role
-
-- `tradesperson` — 83% (12 launched · 10 completed)
-- `content-creator` — 71% (7 launched · 5 completed)
-
-**Average session length:** 3m 41s
-**Knowledge sources clicked:** 14
-```
-
-## How to opt out
-
-Two equivalent switches — either short-circuits before any file opens.
-
-```bash
-# Env (per-shell)
-export AGENT_CONFIG_NO_LOCAL_ANALYTICS=1
-```
-
-```yaml
-# .agent-settings.yml (per-project)
-analytics:
-  local: off
-```
-
-After either is in effect, `emit()` returns `False` and the JSONL is
-never appended. The `show` command still works against existing data,
-so you can opt out without losing what you already have.
-
-## How to delete it
-
-The file is plain JSONL. Delete it:
-
-```bash
-rm -rf ~/.event4u/agent-config/workspace/analytics/
-```
-
-Or prune the rolling window manually:
-
-```bash
-./agent-config analytics prune
-# → pruned 47 event(s)
-```
-
-`prune` drops anything older than 90 days. The lock file prevents two
-concurrent passes from racing each other.
-
-## What this guide does not cover
-
-- **Remote telemetry** — that's the Worker SDK (`packages/telemetry/`).
-  Deployment is out of v0 scope; kill-switch defaults to disabled.
-- **Workspace UI** — Phase 4 builds the browser tab that emits these
-  events. See [`docs/contracts/daily-workspace.md`](../contracts/daily-workspace.md).
-- **Encryption at rest** — Phase 8. Until then, the JSONL is plaintext
-  on your local disk.

package/docs/guides/local-knowledge.md

@@ -1,127 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-24
----
-
-# Local knowledge — 5-minute walkthrough
-
-Point the agent at a folder of local files (PDFs, Markdown, Word docs, spreadsheets). It chunks, redacts PII + secrets, and persists into the agent memory namespace — local-only, single-user, no OAuth, no remote fetch.
-
-Contract: [`local-knowledge-ingestion`](../contracts/local-knowledge-ingestion.md).
-Roadmap home: `agents/roadmaps/archive/road-to-employee-product-and-external-proof.md` Phase 2.
-
-## Prerequisites
-
-- Python 3.10+ on the host.
-- `markitdown` on `PATH` if the corpus contains PDF / DOCX / XLSX / EPUB / images. Pure markdown / text corpora work without it.
-- An `agents/` directory in the project (created by the installer). The `agents/memory/knowledge/` subdirectory is created lazily on first ingest.
-
-## Step 1 — Pick a folder
-
-Anything local works: a customer folder, a project drop, a `.zip` archive, a single PDF. The walk skips hidden dirs (`.git`, `.venv`, `node_modules`) and does not follow symlinks.
-
-For this walkthrough we use a folder with one PDF and three markdown notes:
-
-```text
-/Users/maintainer/clients/acme/
-├── brief.pdf
-├── kickoff-notes.md
-├── meeting-2026-05-12.md
-└── pricing-v3.md
-```
-
-## Step 2 — Ingest
-
-```bash
-/knowledge ingest /Users/maintainer/clients/acme/
-```
-
-Realistic output (your ingest-id will differ — uuid7s are time-ordered):
-
-```text
-✅ ingested 01927f4a-2b1c from /Users/maintainer/clients/acme/
-   documents: 4, chunks: 18, bytes_stored: 47312
-   PII redacted: EMAIL=3, PHONE=1, IBAN=0, CC=0, SSN=0
-   secrets redacted: 0
-   skipped: 0 unsupported MIME
-```
-
-What just happened:
-
-- Each file routed through `markitdown` (PDF) or passthrough (Markdown).
-- Chunks split at ~2 KB boundaries, written to `agents/memory/knowledge/<ingest-id>/chunks/<n>.md`.
-- A `manifest.json` recorded the source path, doc count, redaction counters, and `created_at`.
-- PII regex pass replaced 3 emails + 1 phone with `[EMAIL]` / `[PHONE]` placeholders **before** the chunk hit disk.
-
-> Want the raw text in (no redaction)? `--no-redact`. The manifest captures the flag so the audit row names every bypass. Default is always redact.
-
-## Step 3 — Ask the agent
-
-Use the host model normally. The MCP tool `memory_retrieve` now returns knowledge chunks alongside curated and intake entries — same envelope, with an additional `body.source_kind: knowledge` tag so the model knows the source is user-supplied, not maintainer-curated.
-
-Example prompt:
-
-> *"What does the acme pricing-v3 note say about volume discounts?"*
-
-The agent retrieves the matching chunks (pinned chunks rank slightly higher than unpinned; knowledge entries are discounted ~15 % vs curated so hand-reviewed content still wins on equal relevance) and answers with a citation back to the source path stored in the manifest.
-
-If nothing matches, the model says so. The retrieval surface does not invent a citation.
-
-## Step 4 — List + pin
-
-See what's been ingested:
-
-```bash
-/knowledge list
-```
-
-```text
-ID        DOCS  CHUNKS  BYTES   PINNED  REDACTED  CREATED              SOURCE
-01927f4a  4     18      47312   no      yes       2026-05-25T08:14:02  /Users/maintainer/clients/acme
-```
-
-Pin so it survives LRU eviction when the 500 MB namespace cap is crossed:
-
-```bash
-/knowledge list --pin 01927f4a
-```
-
-```text
-✅ pinned 01927f4a
-```
-
-Prefix must be unambiguous — if it matches > 1 ingest, the command rejects with a structured error and asks for a longer prefix.
-
-## Step 5 — Forget
-
-When the work is done, drop the ingest atomically:
-
-```bash
-/knowledge forget 01927f4a
-```
-
-```text
-✅ forgot 01927f4a — removed 18 chunks, 47312 bytes
-```
-
-Forget is atomic — no partial state. Pinned ingests are dropped the same as unpinned; pinning protects from LRU, not from explicit forget.
-
-## What the guide does **not** cover
-
-- Multi-user share — single-user by design. Multi-user lives behind ADR-024 workspace work and Phase 4 of the parent roadmap.
-- Remote sources — every input must resolve to a local path. `http://`, `https://`, `s3://`, `gs://`, `azure://` are rejected at the input validator.
-- Connector contracts (GitHub / Jira / Confluence) — those sit behind Hard-Floor OAuth and stay cancelled in `road-to-internal-ai-os-deployment.md` Phase 5.
-
-## Troubleshooting
-
-- **"Bound exceeded: total_ingest_size"** — the corpus is > 100 MB. Split it, or ingest a sub-folder.
-- **"Bound exceeded: document_count"** — > 1000 files. Same fix.
-- **"unsupported MIME"** — file skipped, counted in the summary, no chunk written. Add the file as `.md` if you need it indexed.
-- **OCR confidence < 0.7** — the chunk is tagged `low_confidence`. The model still receives it but the citation surface flags the lower confidence.
-- **markitdown not on PATH** — install it (`pip install 'markitdown[all]'`) or pass `--markitdown=<bin>`. Markdown-only corpora work without it.
-
-## See also
-
-- [`local-knowledge-ingestion`](../contracts/local-knowledge-ingestion.md) — contract (input shapes, bounds, storage, redaction).
-- [`/knowledge ingest`](../../dist/agent-src/commands/knowledge/ingest.md) · [`/knowledge list`](../../dist/agent-src/commands/knowledge/list.md) · [`/knowledge forget`](../../dist/agent-src/commands/knowledge/forget.md)
-- [`markitdown` skill](../../dist/agent-src/skills/markitdown/SKILL.md) — peer-side adapter for binary formats.

package/docs/guides/skill-discovery.md

@@ -1,71 +0,0 @@
-# Skill discovery — a 3-minute walkthrough
-
-The package ships 220 skills. You do not need to know them. `/skills:discover`
-turns the catalog into a short, **explained** shortlist for your role — every
-row tells you *why* it is suggested, so you never adopt a skill on faith.
-
-It is local-only: it reads the skill catalog, your role's shortlist, and (if
-present) your local-analytics log. No network, no writes.
-
-## 1. Run it for your role
-
-```
-/skills:discover sales
-```
-
-Or, with a role experience already active, just `/skills:discover` — it picks
-up `roles.active_role` from `.agent-settings.yml`.
-
-Under the hood the command runs:
-
-```bash
-./scripts-run src/scripts/skill_discovery --role sales
-```
-
-## 2. Read the `why` column
-
-The output is a table. The third column is the point — it names the **signal**
-behind each suggestion, never a bare score:
-
-```
-| skill                  | class                   | why                                                       | first command            |
-|------------------------|-------------------------|-----------------------------------------------------------|---------------------------|
-| refine-prompt          | most-useful-for-role    | Tightens fuzzy buyer briefs before drafting               | Skill › refine-prompt     |
-| voice-and-tone-design  | most-useful-for-role    | Locks the deal voice across customer + procurement        | Skill › voice-and-tone-design |
-| competitive-positioning| most-useful-for-role    | Surfaces the ours-vs-theirs delta when a competitor named | Skill › competitive-positioning |
-| activation-design      | related-to-current-task | same domain (product) as your sales core skills           | Skill › activation-design |
-| customer-research      | recently-adopted        | from your role shortlist — no local usage signal yet      | Skill › customer-research |
-| funnel-analysis        | popular-in-role         | from your role shortlist — no local usage signal yet      | Skill › funnel-analysis   |
-```
-
-The four classes:
-
-- **most-useful-for-role** — your role's curated priority shortlist.
-- **related-to-current-task** — same-domain peers you have not shortlisted yet.
-- **recently-adopted** — what you actually used recently (from local analytics);
-  on a fresh machine with no usage history it honestly says *"no local usage
-  signal yet"* and falls back to your shortlist instead of inventing a number.
-- **popular-in-role** — what your role launches most locally (same fallback).
-
-## 3. Adopt one
-
-Pick a row, read its `why`, and start with the `first command`. Unsure what a
-skill will actually do before you commit? Preview it first:
-
-```
-/skill:preview competitive-positioning
-```
-
-That is the safe adoption loop: **discover → preview → run**.
-
-## Notes
-
-- **Local-only.** `/skills:discover` never touches the network and writes
-  nothing. It reads the catalog, your role file, and the optional analytics log.
-- **Analytics is optional.** Opt out with `AGENT_CONFIG_NO_LOCAL_ANALYTICS=1`
-  or `analytics.local: off` in `.agent-settings.yml`. The two usage-driven
-  classes then fall back to your role shortlist — the list is still useful, just
-  without the personalised signal.
-- **`--format json`** emits the same data machine-readably; **`--limit N`** sets
-  how many results per class (default 5).
-- Contract: [`skill-discovery`](../contracts/skill-discovery.md).

package/docs/guides/skill-preview.md

@@ -1,71 +0,0 @@
-# Skill preview — see what a skill does before you run it
-
-With 220 skills and some that run commands, you should not have to run a skill to
-find out what it touches. `/skill:preview` reads a skill's **declared intent** —
-its steps, execution type, tools, and any file/command targets — and renders a
-plain-language summary. Read-only: it never runs the skill.
-
-This is the middle of the safe adoption loop: **discover → preview → run**.
-
-## 1. Discover, then preview
-
-Find a candidate with [`/skills:discover`](skill-discovery.md), then look before you leap:
-
-```
-/skill:preview competitive-positioning
-```
-
-Under the hood:
-
-```bash
-./scripts-run src/scripts/skill_preview competitive-positioning
-```
-
-## 2. Read the summary
-
-A **manual** skill (the default) is pure guidance — preview says so plainly:
-
-```
-# Preview — `accessibility-auditor`
-
-**Execution: instructional only.** This skill does not run anything automatically —
-it guides the agent step by step.
-
-_No tools, commands, or file targets declared — pure guidance._
-```
-
-An **assisted** skill proposes actions you approve — preview surfaces the command
-and tools it declares:
-
-```
-# Preview — `adr-create`
-
-**Execution: assisted** (handler `shell`). It will *propose* actions for you to
-approve — it never executes silently.
-
-This skill will walk these steps:
-- Pick the next ADR number
-- Write the standard template
-- Regenerate the index
-
-Declared command: `./scripts-run src/scripts/adr/regenerate_index`
-```
-
-Add `--technical` for the raw frontmatter + numbered step list.
-
-## 3. Decide, then run
-
-Preview hands the decision back to you. If the declared steps and targets look
-right, invoke the skill. If not, skip it — you have spent zero side effects
-finding out.
-
-## What preview is not
-
-- **Not a sandbox.** It does not run the skill or a fenced copy of it.
-- **Not a safety guarantee.** It shows what the skill *declares* it will touch —
-  it cannot prove a skill with an `execution` block is side-effect-free.
-
-A malformed or missing skill yields a structured error, never a crash.
-
-Contract: [`skill-dry-run`](../contracts/skill-dry-run.md). Pairs with
-[`skill-discovery`](skill-discovery.md) as the discover → preview → run loop.