@oneie/claude 0.5.0 → 0.7.0

package/commands/release.md

@@ -1,144 +1,165 @@
 # /release
 
-**Source of truth:** `one/release.md` · **Script:** `scripts/release.ts`
+Release the ONE OSS template and/or npm packages.
 
-Assemble `release/` from the monorepo, publish npm packages, and push to `github.com/one-ie/one`.
+**Template direction flipped 2026-07-23 — `apps/one/` is now the SINGLE SOURCE OF TRUTH.**
+Real development happens directly in the public clone; `one-ie/template/` is a read-only-by-
+convention **mirror** kept inside the monorepo so `packages/` and `/do` cycles can reference it
+without a second clone. Edit `apps/one` directly, then pull it back:
+**`apps/one/` → `one-ie/template/` (+ `apps/oo/site/`)**. There is deliberately **no**
+template → apps/one push path; the old direction would have destroyed apps/one-only work.
 
-## Modes
+**npm packages:** `packages/{sdk,react,mcp,cli}` → npm registry (a separate job — the release
+script does not publish; see Step 4)
 
-| Invocation | What |
-|-----------|------|
-| `/release` | Stage + publish + push (full pipeline) |
-| `/release --stage` | Assemble `release/` only, no publish, no push |
-| `/release --push` | Stage + push to one-ie/one (skip npm publish) |
-| `/release --dry-run` | Print manifest, no writes |
-
-## The Three Packages
+---
 
-| Package | npm name | Publish from | Depends on |
-|---------|----------|-------------|------------|
-| SDK | `@oneie/sdk` | `release/sdk` | — |
-| CLI | `oneie` | `packages/cli` | `@oneie/sdk` |
-| MCP | `@oneie/mcp` | `release/mcp` | `@oneie/sdk` |
+## Invocations
 
-**Publish order:** SDK first, then CLI + MCP.
+| Command | What |
+|---|---|
+| `/release` | Full pipeline: template pull + npm packages |
+| `/release template` | Pull apps/one into the template mirror and commit in one-ie (no npm publish) |
+| `/release npm` | Bump + build + publish npm packages only |
+| `/release --dry-run` | Print what would happen, no writes |
 
 ---
 
-## Steps
-
-### Step 1 — Stage (`bun run release`)
+## Step 1 — Preflight checks
 
 ```bash
-bun run release          # assembles release/ from monorepo
-bun run release -- --dry-run  # preview only
+# Verify clean working tree
+git diff --exit-code && git diff --cached --exit-code || echo "WARN: uncommitted changes"
+
+# Verify apps/one is cloned
+test -d /Users/toc/Server/apps/one/.git || {
+  echo "Clone first: git clone git@github.com:one-ie/one.git apps/one"
+  exit 1
+}
+
+# Run strip guard — zero moat/do-engine source in the template's site/src/
+# (maintainer-only tooling lives in template-release/, a SIBLING of template/,
+#  and never ships in the published repo)
+cd one-ie/template-release && bash scripts/strip-guard.sh
+
+# Run test suite
+cd one-ie/template-release && bun vitest run
 ```
 
-The script (`scripts/release.ts`) runs six sub-steps:
-
-| Sub-step | What |
-|----------|------|
-| `clean` | Wipe `release/` (preserve `.git`) |
-| `copy` | Run manifest: `agents/templates`, `packages/sdk`, `packages/mcp`, `.claude`, `templates/web` |
-| `one` | Copy `one/` docs filtered by public allowlist (strategy + in-flight work withheld) |
-| `overlay` | Apply `scripts/release-templates/` on top (README.md, CLAUDE.md, AGENTS.md overrides) |
-| `license` | Mirror root `LICENSE` into every slot |
-| `verify` | Assert 4-file convention: `README.md`, `CLAUDE.md`, `AGENTS.md`, `LICENSE` in root + each slot |
+---
 
-**Slots:** `agents/` · `one/` · `sdk/` · `mcp/` · `.claude/` · `web/`
+## Step 2 — Pull apps/one into the template mirror
 
-**Key copies:**
-- `templates/web` → `release/web` (Astro + React template)
-- `packages/sdk` → `release/sdk`
-- `packages/mcp` → `release/mcp`
-- `.claude` → `release/.claude` (excl. `settings.local.json`)
-- `agents/templates` → `release/agents/templates` (real pods withheld)
-- `one/` → `release/one` (allowlist filtered)
+```bash
+cd one-ie/template-release
+bash scripts/release.sh --message "release: $(date +%Y-%m-%d)"
+# flags: --dry-run | --no-push | --message "<note>"
+```
 
-Report: files copied, bytes, ms per sub-step.
+The script (`template-release/scripts/release.sh`):
+1. `rsync` apps/one/ → one-ie/template/ (excludes local-only / secret files)
+2. Sync per-package LICENSE files (`sync-licenses.sh`)
+3. `git commit` (+ push unless `--no-push`) **inside the one-ie monorepo — NOT apps/one.**
+   Nothing here writes to apps/one or to github.com/one-ie/one; that clone owns its own history.
+4. `rsync` apps/one/site/ → apps/oo/site/ (keeps the agency node current, if apps/oo exists)
 
-### Step 2 — Version Bump
+**Paid plugins are not stubbed by this script.** The 5 paid plugins backing `PAID_FEATURES`
+(`one.ie/web/src/lib/billing/gate.ts`) — `plugin-{admin,course,dashboard,premium,shop}` — live in
+`apps/one/packages/` and are mirrored into `template/packages/` unpublished. Their delivery
+mechanism is still undecided: `text/plugin-delivery-plan.md` § Scope correction.
 
-Before publishing, sync versions. SDK must be bumped first:
+---
 
-1. Bump `packages/sdk/package.json` version
-2. Update `packages/cli/package.json` `@oneie/sdk` dep to match
-3. Update `packages/mcp/package.json` `@oneie/sdk` dep to match  
-4. Bump CLI and MCP versions
+## Step 3 — Bump npm package versions (if releasing npm)
 
-**CRITICAL:** `cd packages/sdk` before `npm version` — running from monorepo root triggers lockfile relock.
+Bump order: SDK first, then react/mcp/cli which depend on it.
 
 ```bash
-cd packages/sdk && npm version patch && cd ../..
-cd packages/cli && npm version patch && cd ../..
-cd packages/mcp && npm version patch && cd ../..
+# Check current versions
+grep '"version"' packages/sdk/package.json packages/react/package.json packages/mcp/package.json packages/cli/package.json
+
+# Bump (patch | minor | major)
+cd packages/sdk   && npm version patch && cd ../..
+cd packages/react && npm version patch && cd ../..
+cd packages/mcp   && npm version patch && cd ../..
+cd packages/cli   && npm version patch && cd ../..
+
+# Sync workspace:* deps — update sdk version in react/mcp/cli package.json if pinning
 ```
 
-Re-run `bun run release` after bumping so `release/sdk` and `release/mcp` reflect new versions.
+**CRITICAL:** Run `npm version` from each package dir, not the monorepo root (triggers lockfile relock).
+
+---
 
-### Step 3 — Build + Publish
+## Step 4 — Build + publish npm packages
 
-SDK must publish before CLI and MCP resolve it.
+SDK must publish before react/mcp/cli (they declare `@oneie/sdk` as a dependency).
 
 ```bash
-# SDK
-cd release/sdk && bun run build && npm publish --access public && cd ../..
+# Build all packages
+cd packages && bun run build && cd ..
+
+# Verify npm token is set
+npm whoami
 
-# CLI (publishes from packages/cli, not release/)
-cd packages/cli && npm run build && npm publish --access public && cd ../..
+# Publish SDK first
+cd packages/sdk && npm publish --access public && cd ../..
 
-# MCP
-cd release/mcp && bun run build && npm publish --access public && cd ../..
+# Then react, mcp, cli (parallel is fine — SDK is already on registry)
+cd packages/react && npm publish --access public && cd ../..
+cd packages/mcp   && npm publish --access public && cd ../..
+cd packages/cli   && npm publish --access public && cd ../..
 ```
 
-### Step 4 — Push to github.com/one-ie/one
+**Gotcha:** `workspace:*` deps must be temporarily pinned to `^x.y.z` before publishing, then restored. See memory entry `reference_oneie_npm_publish_workspace`.
 
-```bash
-bun run release -- --push
-```
+**The other npm packages have their own door.** `@oneie/design`, `@oneie/frontend`, and the 9
+free plugins (auth/backend/blog/booking/chat/docs/mail/media/track) publish per-package via
+`bash packages/publish-plugin.sh <plugin-dir-name> [--dry-run]` — it rewrites `workspace:*`
+peers to a loose optional `*` and restores `package.json` on exit. It **hard-refuses** the 5
+paid plugins unconditionally, even with `--dry-run`: public npm has no purchase gate. Do not
+remove that block to work around it.
 
-The `--push` flag (built into `scripts/release.ts`):
-1. `git init` inside `release/` if no `.git` (first time)
-2. `git remote add origin git@github.com:one-ie/one.git`
-3. `git add .`
-4. `git commit -m "release: v<version>"`
-5. `git push -u origin main`
+---
 
-### Step 5 — Report
+## Step 5 — Tag + report
 
+```bash
+# Tag the release on main
+VERSION=$(node -p "require('./packages/sdk/package.json').version")
+git tag "v$VERSION" && git push origin "v$VERSION"
 ```
-Stage:     clean 12ms  copy 340ms  one 28ms  overlay 5ms  license 2ms  verify 3ms
-           487 files, 4.2MB  total 390ms
-Publish:   @oneie/sdk@0.8.0 ✓  oneie@3.8.3 ✓  @oneie/mcp@0.2.0 ✓
-Push:      ✓ github.com/one-ie/one  commit: release: v0.8.0
+
+Report format:
+```
+Template:  strip-guard ✓  N/N tests ✓  pulled apps/one → template/  committed in one-ie
+npm:       @oneie/sdk@0.14.0 ✓  @oneie/react@0.14.0 ✓  @oneie/mcp@0.14.0 ✓  @oneie/cli@0.14.0 ✓
+Tag:       v0.14.0 → main
 ```
 
 ---
 
-## Manifest Reference (`scripts/release.ts`)
-
-```typescript
-const manifest = [
-  { from: 'agents/templates', to: 'agents/templates' },
-  { from: 'packages/sdk',    to: 'sdk',    exclude: ['node_modules', 'dist'] },
-  { from: 'packages/mcp',    to: 'mcp',    exclude: ['node_modules', 'dist'] },
-  { from: '.claude',         to: '.claude', exclude: ['settings.local.json'] },
-  { from: 'templates/web',   to: 'web',    exclude: ['node_modules', 'dist', '.astro'] },
-]
-// one/ is filtered separately by ONE_PUBLIC_DOCS allowlist
-// README.md + CLAUDE.md come from scripts/release-templates/ overlay (NOT monorepo root)
-```
+## x402-gated plugins
+
+**Design, not shipped.** `release.sh` does not stub paid plugins and there is no `PAID_PLUGINS`
+array in it — the x402 delivery path (`pay.one.ie/x/<name>.js`) is the undecided half of
+`text/plugin-delivery-plan.md`. What IS enforced today is the refusal: `packages/publish-plugin.sh`
+blocks the 5 paid plugins from npm, and they ship to nobody until that plan lands.
+
+The paid set is defined in one place — `PAID_FEATURES` in `one.ie/web/src/lib/billing/gate.ts`,
+mirrored by the `PAID_PLUGINS` string in `packages/publish-plugin.sh`. Adding a paid plugin means
+editing both, not a release-script array.
 
 ---
 
 ## Gotchas
 
-- **Internal CLAUDE.md never ships** — it's 43KB of private dev context; the overlay provides a clean public version
-- **`one/` is default-deny** — only files in `ONE_PUBLIC_DOCS` allowlist ship; strategy/partnership docs stay private
-- **SDK publishes first** — CLI and MCP declare `@oneie/sdk` as dependency; registry must have it before they resolve
-- **`release/.git` persists** — `clean` step preserves `.git` so `release/` stays a live checkout of `one-ie/one`
-- **CLI publishes from `packages/cli`** — not `release/`; there's no `release/cli` slot
+- **`workspace:*` must be pinned before publish** — bun/npm won't rewrite it; pin → publish → restore
+- **npm token** — automation token stored in memory as `reference_npm_token` (expires 2026-08-26)
+- **SDK publishes first** — registry must have it before react/mcp/cli resolve it
+- **Paid plugin source never ships** — `strip-guard.sh` verifies this; if it fails, fix before publish
+- **`apps/one` is never written by `release.sh`** — it is the SSOT and owns its own history; the commit lands in the one-ie monorepo. Anything the mirror has that apps/one lacks must be moved by hand, deliberately.
 
 ---
 
-*Stage. Publish. Push. The release/ directory IS the one-ie/one repo. Three packages, one truth.*
+*apps/one is the source; the template mirrors it via rsync. Paid plugins ship to nobody yet. npm packages publish in dependency order.*

package/commands/restart.md

@@ -0,0 +1,53 @@
+# /restart — Fast dev server restart
+
+Kill Astro (4321–4329), gateway (8788), and channels (8787) servers, then start fresh + sync D1. No cache clearing, no reinstall — just stop and go.
+
+Use when: you want a clean restart without the full `/kill` overhead. Takes ~15s vs ~30s.
+
+## What it does
+
+```
+1. Kill all three servers (ports 4321–4329, 8787–8799)
+2. Sync prod D1 → local miniflare
+3. Start Astro (4321) + gateway (8788) + channels (8787) in parallel
+```
+
+## Steps
+
+**Step 1 — kill:**
+```bash
+cd /Users/toc/Server/one-ie/one.ie/web && \
+  (lsof -ti:4321,4322,4323,4324,4325,4326,4327,4328,4329,8787,8788,8789,8790,8791,8792,8793,8794,8795,8796,8797,8798,8799 2>/dev/null | xargs kill -9 2>/dev/null; \
+   pkill -f "one\.ie/web.*(astro|wrangler|local-gateway)" 2>/dev/null; true)
+```
+
+**Step 2 — db-sync (blocking, must finish before servers start):**
+```bash
+cd /Users/toc/Server/one-ie/one.ie/web && bun run db:sync
+```
+
+**Step 3 — start three servers (three separate background Bash calls, all in parallel):**
+```bash
+# Astro — web UI
+cd /Users/toc/Server/one-ie/one.ie/web && bun run dev
+
+# Gateway — TypeDB-backed local gateway on 8788
+cd /Users/toc/Server/one-ie/one.ie/web && bun run dev:gateway
+
+# Channels worker — wrangler on 8787 (`bun run dev` = bare `wrangler dev`)
+cd /Users/toc/Server/one-ie/channels && bun run dev
+```
+
+`/kill` puts `one.ie/web`'s `dev:wrangler` on 8787 instead. Only one of the two
+can hold that port — don't run both; the second bind fails.
+
+Poll `http://localhost:4321/` until 200, then confirm all three up:
+- Astro: http://localhost:4321 → 200
+- Gateway: http://localhost:8788 → 404 (expected)
+- Channels: http://localhost:8787 → 401 (expected)
+
+## When to use /kill instead
+
+- HMR broken / duplicate React hooks → `/kill` (clears Vite cache)
+- Dep version drift → `/kill` (reinstalls)
+- Ghost port won't release → `/kill`

package/commands/see.md

@@ -13,11 +13,11 @@ Read the world — query substrate state without emitting signals.
 | `toxic` | Blocked paths — resistance > strength | L3 |
 | `frontiers` | Unexplored tag clusters (<10% traversed) | L7 |
 | `paths [--from X] [--to Y]` | Any path query by source/target | L2 |
-| `hypotheses` | Permanent knowledge (hardened by L6) | L6 |
+| `hypotheses` | Hardened learning (persisted by L6) | L6 |
 | `evolved` | Agents that rewrote their system prompts | L5 |
 | `revenue` | Per-path earnings from L4 economic loop | L4 |
 | `events [--since T]` | Signal history and Four Outcomes audit | L1 |
-| `memory <uid>` | Full memory card for an actor (reveal) | L6 |
+| `memory <uid>` | Unseal one PII field for an actor (reveal) — authenticated | L6 |
 
 ## Routing
 
@@ -26,22 +26,30 @@ No mark(), no warn(), no side effects. Every noun is read-only.
 
 | Noun | Primitive | Source |
 |------|-----------|--------|
-| tasks | `follow()` queue read | `/api/tasks` or `scanTodos()` |
-| highways | `follow()` path read | `/api/state` strength ≥ 50 |
-| toxic | `follow()` path read | `/api/state` resistance > strength |
-| frontiers | `follow()` gap read | `/api/state` <10% traversed |
-| paths | `follow()` path query | `/api/state` filtered |
-| hypotheses | TypeDB read | knowledge entities |
-| evolved | TypeDB read | units where generation > 1 |
-| revenue | TypeDB read | paths with revenue attribute |
-| events | TypeDB read | signal history |
-| memory | `reveal(uid)` | `/api/memory/reveal/:uid` |
+| tasks | `follow()` queue read | `.claude/scripts/do-rank.py` |
+| highways | `follow()` path read | `GET /api/export/highways` |
+| toxic | `follow()` path read | `GET /api/export/toxic` |
+| frontiers | `follow()` gap read | `GET /api/frontiers` |
+| paths | `follow()` path query | `GET /api/paths` |
+| hypotheses | TypeDB read | `GET /api/export/hypotheses` |
+| evolved | TypeDB read | `GET /api/export/units`, filter `generation > 1` |
+| revenue | TypeDB read | `GET /api/revenue` |
+| events | TypeDB read | signal history — no GET route (see below) |
+| memory | `reveal(uid)` | `GET /api/pii/reveal/:uid?field=` |
+
+**Not built (do not invoke, do not describe as live) — verified 2026-08-02:**
+`GET /api/tasks`, `GET /api/state`, `GET /api/memory/reveal/:uid`, and
+`scanTodos()` in `src/engine/task-parse.ts` (the whole `src/engine/` dir holds
+only `rubric.ts`). Every noun that used to name one has been repointed above.
+`/api/events` exists but is **POST-only tracking ingest**, not a signal-history
+read — do not GET it.
 
 ## Steps
 
 ### tasks
 
-1. GET `http://localhost:4321/api/tasks` (falls back to `scanTodos()` in `src/engine/task-parse.ts` if server not running)
+1. `python3 .claude/scripts/do-rank.py` — the ranker reads `text/*-todo.md` directly and needs no dev server. Add `--tasks` for the tagged-signal view, `--json` for machine output, `--top N` to cap.
+   - **The one exception to this file's no-side-effects rule.** The ranker refreshes a `text/task-paths.json` memo as it runs. It does **not** write `todo.md` — that is `hook:sync-priority-todo`, fired on Stop and SessionStart. No substrate write, no `mark()`/`warn()`.
 2. Filter by `$ARGUMENTS` if provided — tags or phase (e.g. `/see tasks build P0`, `/see tasks C1`)
 3. Report tasks sorted by effective priority (priority score + pheromone strength − resistance):
    - Name, id, priority formula (e.g. `90 = critical=30 + C1=40 + dev=20`)
@@ -56,7 +64,7 @@ No mark(), no warn(), no side effects. Every noun is read-only.
 
 ### highways
 
-1. GET `http://localhost:4321/api/export/highways?context=1` (falls back to `/api/state` if server not running)
+1. GET `http://localhost:4321/api/export/highways?limit=50` — the route takes `limit` (default 50, capped 200) and an optional `from=<aid>` to scope to one source actor. There is no `context=` param and no `/api/state` fallback.
 2. Show paths where `strength ≥ 50`, sorted by strength desc (default limit 20; use `--limit N` to override)
 3. Each: from → to, strength, traversals, revenue — and `context: <docs>` if contextHint is present
 4. Report:
@@ -69,7 +77,8 @@ No mark(), no warn(), no side effects. Every noun is read-only.
 
 ### toxic
 
-1. GET `http://localhost:4321/api/state`
+1. GET `http://localhost:4321/api/export/toxic?limit=200` (limit capped at 500; returns warned/faded paths with `resistance > 0`, sorted by resistance desc)
+   - **Empty ≠ clean.** Every `/api/export/*` route scopes via `scopeToGroup(viewer, …)`, defaulting to `viewer='end_user'` / `workspace='default'`. An unauthenticated call returns an empty set, not a 401 — so "0 toxic paths" may mean "not authorized to see any". The same applies to `hypotheses` and `evolved` below. Authenticate, or read the count as unknown.
 2. Show paths where `resistance > strength`
 3. Each: from → to, resistance, strength, hypothesis (if any)
 4. Report:
@@ -80,7 +89,7 @@ No mark(), no warn(), no side effects. Every noun is read-only.
 
 ### frontiers
 
-1. GET `http://localhost:4321/api/state`
+1. GET `http://localhost:4321/api/frontiers` (optional `?limit=N`)
 2. Show tag clusters with <10% traversal rate
 3. Each: tag cluster, % explored, expected value
 4. Report:
@@ -91,14 +100,14 @@ No mark(), no warn(), no side effects. Every noun is read-only.
 
 ### paths
 
-1. GET `http://localhost:4321/api/state`
-2. Filter by `--from` and/or `--to` if provided in `$ARGUMENTS`
+1. GET `http://localhost:4321/api/paths` — params are `from=<aid>`, `to=<aid>`, `limit` (default 20), `min_strength` (default 1)
+2. Filter by `--from` and/or `--to` if provided in `$ARGUMENTS` — pass them through as `from=`/`to=`
 3. Show matching paths: from → to, strength, resistance, net weight (strength − resistance)
 4. Report all matching paths with full pheromone state
 
 ### hypotheses
 
-1. Query TypeDB: match hypothesis entities
+1. GET `http://localhost:4321/api/export/hypotheses?limit=100` (or query TypeDB directly for hypothesis entities)
 2. Show each: pattern, confidence, created, reinforced count
 3. Report:
    ```
@@ -108,7 +117,7 @@ No mark(), no warn(), no side effects. Every noun is read-only.
 
 ### evolved
 
-1. Query TypeDB: units where `generation > 1`
+1. GET `http://localhost:4321/api/export/units`, then filter to `generation > 1` client-side (the route has no generation filter) — or query TypeDB directly
 2. Show each: uid, name, generation, current model, last evolution timestamp
 3. Report:
    ```
@@ -118,7 +127,7 @@ No mark(), no warn(), no side effects. Every noun is read-only.
 
 ### revenue
 
-1. Query TypeDB: paths with revenue attribute, sorted desc
+1. GET `http://localhost:4321/api/revenue` (or query TypeDB for paths with a revenue attribute, sorted desc)
 2. Show per-path earnings
 3. Report:
    ```
@@ -128,7 +137,7 @@ No mark(), no warn(), no side effects. Every noun is read-only.
 
 ### events
 
-1. Query TypeDB signals, optionally filtered by `--since T` from `$ARGUMENTS`
+1. Query TypeDB signals directly, optionally filtered by `--since T` from `$ARGUMENTS`. **No HTTP read route exists** — `/api/events` is POST-only tracking ingest and will not serve this.
 2. Show each signal: receiver, data summary, outcome, timestamp
 3. Report:
    ```
@@ -139,23 +148,24 @@ No mark(), no warn(), no side effects. Every noun is read-only.
 ### memory
 
 1. Extract `<uid>` from `$ARGUMENTS` (e.g. `/see memory person:a7f3`)
-2. GET `http://localhost:4321/api/memory/reveal/<uid>`
-3. Display the full MemoryCard:
-   - **Actor**: uid, kind, firstSeen
-   - **Hypotheses**: pattern + confidence (asserted capped at 0.30)
-   - **Highways**: top paths by strength
-   - **Signals**: last 200 episodes
-   - **Groups**: memberships
-   - **Capabilities**: offered skills + prices
-   - **Frontier**: unexplored tag clusters
-4. Report:
+2. GET `http://localhost:4321/api/pii/reveal/<uid>?field=email` — this is the only
+   shipped `reveal`. It unseals **one PII field at a time**
+   (`email|phone|address|name|dob|custom`), not a memory card.
+   - **Authenticated and audited.** It calls `requireAuth` + `requireContactOwner`,
+     so an anonymous or non-owning caller gets denied. Rate-limited to 100
+     reads/hour per reader; every read emits a `pii.read` audit event.
+   - The MCP tool `reveal` is the same route.
+3. Report:
    ```
-   Memory: <uid>
-   Hypotheses: N  (observed=X  asserted=Y)
-   Highways: N paths
-   Frontier: [tag1, tag2, ...]  — N unexplored tags
+   Reveal: <uid>  field=<field>
    ```
 
+**The aggregate MemoryCard was never built.** There is no route returning
+hypotheses + highways + last-200 signals + groups + capabilities + frontier for
+one actor. To assemble that view today, compose the other nouns for that uid:
+`/see hypotheses`, `/see highways` (`?from=<uid>`), `/see paths` (`?from=<uid>`),
+`/see frontiers`. Do not describe a single-call memory card as live.
+
 ---
 
 *Every `/see` query is a `follow()` call — the substrate answers without learning.*

package/commands/skill-create.md

@@ -27,7 +27,7 @@ tail -5 text/learnings.md
 
 # Recent cycle diff (what actually changed)
 git diff HEAD~1 HEAD --stat
-git diff HEAD~1 HEAD -- $(git diff HEAD~1 HEAD --name-only | grep -v 'text/\|text/' | head -20)
+git diff HEAD~1 HEAD -- $(git diff HEAD~1 HEAD --name-only | grep -v 'text/' | head -20)
 ```
 
 **Step 2 — Extract the pattern (Haiku · low)**
@@ -42,9 +42,25 @@ Ignore one-off specifics (feature names, slugs). Keep the reusable skeleton.
 
 **Step 3 — Write `.claude/skills/<slug>/SKILL.md`**
 
+The path is `.claude/skills/<slug>/SKILL.md` — a **directory** containing
+`SKILL.md`. A bare `.claude/skills/<slug>.md` is not loaded by the runtime
+(several flat files there — `build.md`, `typecheck.md`, `dev.md`, `signal.md`,
+`cloudflare.md`, the `rag-*.md` set — exist as canon but never trigger as skills).
+
+The YAML frontmatter is **load-bearing, not decoration**: `name` and
+`description` are what the runtime matches against to decide whether to surface
+the skill. A SKILL.md with no frontmatter never triggers. Put the trigger phrases
+in `description` — the `## When to use` body section is read only *after* the
+skill has already been selected.
+
 Use this template:
 
 ```markdown
+---
+name: <slug>
+description: <what this does, then the trigger conditions — "Use when …". Include the literal phrases a user would type. This field is the whole triggering surface.>
+---
+
 # <title> skill
 
 <one-sentence description — what this skill does for the model>
@@ -65,14 +81,31 @@ Use this template:
 
 **Step 4 — Wire it (if applicable)**
 
-- If the skill has a natural trigger phrase, append a row to the skills table in
-  `.claude/CLAUDE.md` so it auto-loads.
+- Auto-loading comes from the frontmatter `description`, not from any index —
+  get the trigger phrases into that field or the skill stays dark.
+- Then add the name to the `skills/` line in `.claude/CLAUDE.md` § Structure so
+  the harness inventory stays true. That listing is documentation of what exists;
+  it does not itself wire anything.
 - If it extends an existing skill, note the relation.
 
 **Step 5 — Close**
 
-Emit `signal("learning:harden", 1, "skill=<slug>")` and append one line to
-`text/learnings.md`:
+Append one line to `text/learnings.md`. That line **is** the close — it is
+deterministic and it is what the next cycle reads.
+
+Do **not** emit `learning:harden` or `learning:know`. Neither is a registered
+receiver: `grep -c '"learning:' packages/sdk/src/receivers.ts` → **0**. The
+earlier version of this step instructed `signal("learning:know", { skill })`,
+which fails silently — the same defect its own warning described, one line
+down. The whole `learning:` namespace is unregistered; `harden`'s only shipped
+wire is `chat:harden`, which needs a threadable `entityId` and does not fit a
+skill close.
+
+If you want the creation recorded in the substrate, `skill:save` is real
+(`packages/sdk/src/receivers.ts`). Check the receiver exists before emitting —
+the signature is `signal(receiver, data)`, and there is no three-argument form.
+
+The line:
 
 ```
 - YYYY-MM-DD · skill:<slug> · crystallised from <source-slug> · source=skill-create