@aitne-sh/aitne 0.1.9 → 0.1.11

package/agent-assets/skills/user-interview/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: user-interview
-description: Read or modify the profile-interview queue at agent/profile-questions.md. Pick a question (latent), weave a latent question into a natural reply, tick when the user answers, fallback-promote stale rows, or reconcile against user/*.md. Never sends cold standalone DMs.
+description: Use during morning routine Step 7.5, DM replies, the morning briefing, and the evening sweep to manage the profile-interview queue at state/profile-questions.md — pick a latent question, weave it into a natural reply, tick when answered, fallback-promote stale rows.
 allowed-tools:
   - Bash(curl *)
   - Read
@@ -94,7 +94,7 @@ Before scheduling or asking, every callsite SHOULD verify the target
 slot is genuinely empty:
 
 ```bash
-curl -s "http://localhost:8321/api/profile-questions/slot-filled?path=user/profile.md&section=Identity&anchor=Name"
+curl -s "http://localhost:8321/api/profile-questions/slot-filled?path=identity/profile.md&section=Identity&anchor=Name"
 # → {"filled":true|false,"sectionPresent":true|false,"fileExists":true|false,...}
 ```
 
@@ -109,59 +109,16 @@ the op-morning reference below.
 
 {{> ref:op-morning }}
 
-## Operation 2 — Latent opportunity check (DM handler)
+## Operations 2 & 4 — DM-handler weave and answer capture
 
-Run this AFTER the standard "Capture user info" block in
-`message.received.dm.md` / `message.received.dm_first.md`, BEFORE
-composing the reply.
+DM-handler-only. Operation 2 (latent opportunity check) runs AFTER the
+standard "Capture user info" block in `message.received.dm.md` /
+`message.received.dm_first.md`, BEFORE composing the reply; Operation 4
+(answer capture) runs after Operation 2's opportunity check. The
+slot-filled pre-check, naturalness rules, two PATCHes, and the "one DM =
+one tick" rationale are in the op-dm-handler reference below.
 
-```
-1. GET agent/profile-questions.md ## In Progress.
-2. If no entry has state=latent, skip — return to the normal reply path.
-2.5 Slot-filled pre-check (MANDATORY before any weaving decision).
-   GET /api/profile-questions/slot-filled?path=<target>&section=<section?>&anchor=<anchor?>
-   for the latent row's target. If `filled: true`, the slot was filled
-   between morning routine and now (the user may have volunteered the
-   answer in a previous DM, or the sweep that runs at 17:50 hasn't
-   caught up yet). Resolve the row instead of weaving:
-     - Tick the matching ## Pending row [ ] → [x] (read-rebuild + replace).
-     - Remove the entry from ## In Progress.
-     - Append `- [x] <today> → <id> (reconciled:opportunity)` to ## Answered.
-     - Remove the matching `Profile question (latent): <id>` line from
-       today.md ## Agent Notes.
-   Return to the normal reply path — DO NOT weave a question. The user
-   has effectively already answered it.
-3. Otherwise (slot still empty), judge whether the inbound DM is a
-   natural moment to ask the question. The criteria:
-     - Topic match. The user's message touches the question's domain
-       (work questions when the user mentions a meeting, code, deadline;
-       personal questions when the user discusses lifestyle, hobbies,
-       weekend plans; identity / location questions when the user makes
-       a general greeting on day 1 or asks for time/weather).
-     - Length appropriateness. Your reply will be more than a one-liner;
-       there is room to weave a question without making the message look
-       forced.
-     - Mood appropriateness. The user is not venting / in crisis / asking
-       a single short factual question.
-4. If yes:
-     a. Compose the reply with the question woven in NATURALLY. Do NOT
-        make a separate paragraph or "By the way, …" preamble. The
-        question should feel like a side comment, not an interview cue.
-     b. After the reply is ready (final assistant text already includes
-        the question), issue **two PATCH replaces** (separate calls —
-        they target different files):
-        - `PATCH /api/context/state/profile-questions` section=in_progress
-          — flip the entry to
-          `state=asked :: since=<unchanged> :: asked_at=<current_time>`
-          (preserve the original `since=` date).
-        - `PATCH /api/context/state/today` section=agent_notes — replace the
-          parenthetical from `(latent)` to `(asked HH:MM)` and append
-          `(asked HH:MM)` to the same line; preserve every other Agent
-          Notes line byte-for-byte.
-5. If no, leave the latent entry untouched. Return to the normal reply
-   path. The opportunity will come (or the evening sweep will eventually
-   promote to a fallback scheduled DM if it doesn't).
-```
+{{> ref:op-dm-handler }}
 
 ## Operation 3 — Latent piggyback (morning briefing composition)
 
@@ -172,35 +129,6 @@ op-briefing reference below.
 
 {{> ref:op-briefing }}
 
-## Operation 4 — Capture the answer (DM handler queue reconcile)
-
-Run this AFTER "Capture user info" and Operation 2's opportunity check,
-BEFORE composing the reply text.
-
-```
-1. GET agent/profile-questions.md ## In Progress.
-2. If an entry has state=asked AND (now − asked_at) < 24h:
-     a. Tick the matching ## Pending row [ ] → [x] via PATCH replace
-        (read-rebuild full Pending body, change just that one line).
-     b. Remove the entry from ## In Progress (PATCH replace).
-     c. Append `- [x] <today> → <id> (DM)` to ## Answered.
-     d. Remove the matching today.md ## Agent Notes line — match by
-        the `Profile question (` prefix and the `: <id>` id segment;
-        works for both `(asked HH:MM)` and `(latent)` parenthetical
-        states (PATCH replace, read-rebuild — preserve every other line
-        byte-for-byte). Without this the line lingers in today.md
-        until tomorrow's PUT-replace and confuses the user.
-3. If state=latent or state=scheduled, leave the entry alone — this
-   inbound DM is by definition unrelated to a question the user has
-   not been asked.
-```
-
-The "one DM after fire = one tick" rule is intentional. Trying to detect
-"did the user ACTUALLY answer?" is unreliable and would re-ask forever
-on partial answers. The 7-day `last_attempted` cooldown means an
-unresolved fact will surface again later through the natural-volunteering
-path or the next opportunity.
-
 {{> ref:sweep-and-fallback }}
 
 ## Today.md surfacing — Agent Notes flavor
@@ -258,20 +186,17 @@ those bullets and the system degrades to Layer-4-only protection
 curl -s http://localhost:8321/api/context/state/profile-questions
 
 # Slot-filled probe
-curl -s "http://localhost:8321/api/profile-questions/slot-filled?path=user/profile.md&section=Identity&anchor=Name"
+curl -s "http://localhost:8321/api/profile-questions/slot-filled?path=identity/profile.md&section=Identity&anchor=Name"
 
 # Section-level edit (queue file uses the standard context API)
 curl -s -X PATCH http://localhost:8321/api/context/state/profile-questions \
   -H 'Content-Type: application/json' \
   -d '{"section": "in_progress", "mode": "replace", "content": "- name :: state=latent"}'
 
-# Fallback DM scheduling (Operation 5B only)
-# `prompt` is REQUIRED (the wake-up session has NO memory — it is the only
-# instruction). `description` stays as the short label whose
-# `profile_interview:<id>` prefix triggers the Operation 6 sub-flow.
-curl -s -X POST http://localhost:8321/api/schedule \
-  -H 'Content-Type: application/json' \
-  -d '{"time":"<ISO>","taskType":"dm_session","prompt":"profile_interview:<id> — run the scheduled.dm ## Profile interview sub-flow (Operation 6): fire-time slot-filled abort check, then compose one short natural DM around <hint>.","description":"profile_interview:<id> — <hint>","tier":"medium","taskContext":{"scheduledBy":"user_profile_sweep_fallback","queueId":"<id>","importance":"low"}}'
+# Fallback DM scheduling (Operation 5B only) — see the canonical
+# POST /api/schedule example in references/sweep-and-fallback.md Op 5B.
+# `prompt` is REQUIRED (the wake-up session has NO memory); `description`
+# carries the `profile_interview:<id>` prefix that triggers Operation 6.
 ```
 
 The PATCH `section` argument is snake_case of the heading: `pending`,

package/agent-assets/skills/user-interview/references/op-briefing.md

@@ -12,7 +12,7 @@ composes; it is one of the few naturally-occurring opportunities to
 slip in a question without surfacing a cold standalone DM.
 
 ```
-1. GET agent/profile-questions.md ## In Progress.
+1. GET state/profile-questions.md ## In Progress.
 2. If no entry has state=latent, skip.
 2.5 Slot-filled pre-check (MANDATORY). Same recipe as Operation 2
    step 2.5: GET /api/profile-questions/slot-filled. If

package/agent-assets/skills/user-interview/references/op-dm-handler.md

@@ -0,0 +1,88 @@
+---
+kind: reference
+name: op-dm-handler
+description: Operations 2 and 4 — the DM-handler latent-opportunity weave and the answer-capture queue reconcile. Slot-filled pre-check, naturalness rules, two PATCHes, the "one DM = one tick" rationale.
+---
+
+# Operation 2 — Latent opportunity check (DM handler)
+
+Run this AFTER the standard "Capture user info" block in
+`message.received.dm.md` / `message.received.dm_first.md`, BEFORE
+composing the reply.
+
+```
+1. GET state/profile-questions.md ## In Progress.
+2. If no entry has state=latent, skip — return to the normal reply path.
+2.5 Slot-filled pre-check (MANDATORY before any weaving decision).
+   GET /api/profile-questions/slot-filled?path=<target>&section=<section?>&anchor=<anchor?>
+   for the latent row's target. If `filled: true`, the slot was filled
+   between morning routine and now (the user may have volunteered the
+   answer in a previous DM, or the sweep that runs at 17:50 hasn't
+   caught up yet). Resolve the row instead of weaving:
+     - Tick the matching ## Pending row [ ] → [x] (read-rebuild + replace).
+     - Remove the entry from ## In Progress.
+     - Append `- [x] <today> → <id> (reconciled:opportunity)` to ## Answered.
+     - Remove the matching `Profile question (latent): <id>` line from
+       today.md ## Agent Notes.
+   Return to the normal reply path — DO NOT weave a question. The user
+   has effectively already answered it.
+3. Otherwise (slot still empty), judge whether the inbound DM is a
+   natural moment to ask the question. The criteria:
+     - Topic match. The user's message touches the question's domain
+       (work questions when the user mentions a meeting, code, deadline;
+       personal questions when the user discusses lifestyle, hobbies,
+       weekend plans; identity / location questions when the user makes
+       a general greeting on day 1 or asks for time/weather).
+     - Length appropriateness. Your reply will be more than a one-liner;
+       there is room to weave a question without making the message look
+       forced.
+     - Mood appropriateness. The user is not venting / in crisis / asking
+       a single short factual question.
+4. If yes:
+     a. Compose the reply with the question woven in NATURALLY. Do NOT
+        make a separate paragraph or "By the way, …" preamble. The
+        question should feel like a side comment, not an interview cue.
+     b. After the reply is ready (final assistant text already includes
+        the question), issue **two PATCH replaces** (separate calls —
+        they target different files):
+        - `PATCH /api/context/state/profile-questions` section=in_progress
+          — flip the entry to
+          `state=asked :: since=<unchanged> :: asked_at=<current_time>`
+          (preserve the original `since=` date).
+        - `PATCH /api/context/state/today` section=agent_notes — replace the
+          parenthetical from `(latent)` to `(asked HH:MM)` and append
+          `(asked HH:MM)` to the same line; preserve every other Agent
+          Notes line byte-for-byte.
+5. If no, leave the latent entry untouched. Return to the normal reply
+   path. The opportunity will come (or the evening sweep will eventually
+   promote to a fallback scheduled DM if it doesn't).
+```
+
+# Operation 4 — Capture the answer (DM handler queue reconcile)
+
+Run this AFTER "Capture user info" and Operation 2's opportunity check,
+BEFORE composing the reply text.
+
+```
+1. GET state/profile-questions.md ## In Progress.
+2. If an entry has state=asked AND (now − asked_at) < 24h:
+     a. Tick the matching ## Pending row [ ] → [x] via PATCH replace
+        (read-rebuild full Pending body, change just that one line).
+     b. Remove the entry from ## In Progress (PATCH replace).
+     c. Append `- [x] <today> → <id> (DM)` to ## Answered.
+     d. Remove the matching today.md ## Agent Notes line — match by
+        the `Profile question (` prefix and the `: <id>` id segment;
+        works for both `(asked HH:MM)` and `(latent)` parenthetical
+        states (PATCH replace, read-rebuild — preserve every other line
+        byte-for-byte). Without this the line lingers in today.md
+        until tomorrow's PUT-replace and confuses the user.
+3. If state=latent or state=scheduled, leave the entry alone — this
+   inbound DM is by definition unrelated to a question the user has
+   not been asked.
+```
+
+The "one DM after fire = one tick" rule is intentional. Trying to detect
+"did the user ACTUALLY answer?" is unreliable and would re-ask forever
+on partial answers. The 7-day `last_attempted` cooldown means an
+unresolved fact will surface again later through the natural-volunteering
+path or the next opportunity.

package/agent-assets/skills/user-interview/references/op-morning.md

@@ -8,11 +8,11 @@ description: Operation 1 — pick a profile-interview question during Morning Ro
 
 Run this only inside `routine.morning_routine` (and its split
 variants `routine.morning_routine_today`). DM handlers, scheduled.dm
-briefings, and hourly checks do not run this operation — they use
+briefings, and activity scans do not run this operation — they use
 Operation 2 / 3 / 4 instead.
 
 ```
-1. GET agent/profile-questions.md.
+1. GET state/profile-questions.md.
 2. Skip the entire step if any of:
      - ## In Progress is non-empty.
      - ## Pending is empty.

package/agent-assets/skills/user-interview/references/sweep-and-fallback.md

@@ -79,7 +79,7 @@ Triggered when a `dm_session` task description starts with
 5B) where 3 days passed without a natural opportunity.
 
 ```
-1. Fire-time abort. GET agent/profile-questions.md and the row's
+1. Fire-time abort. GET state/profile-questions.md and the row's
    target_path. Call /api/profile-questions/slot-filled. If the slot is
    filled per the heuristic OR the matching Pending row is no longer
    `[ ]`:

package/agent-assets/skills/user-profile/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: user-profile
-description: Record user facts — identity, people, work, expertise, habits, goals, tendencies. Top-level → user/profile.md; detail → user/<topic>.md. Tone/style/voice/language are NOT facts — route to PATCH /api/config/character. Same turn as reply. Skip duplicates. Never notify.
+description: Record user facts — identity, people, work, expertise, habits, goals, tendencies. Top-level → identity/profile.md; detail → identity/<topic>.md. Tone/style/voice/language are NOT facts — route to PATCH /api/config/character. Same turn as reply. Skip dupes. Never notify.
 allowed-tools:
   - Bash(curl *)
   - Read
@@ -8,11 +8,11 @@ allowed-tools:
 
 # User Profile Update Guide
 
-Output language: `identity/profile.md` and `user/*.md` are Policy B — see `<output_language_policy>`. Template H2 headers stay English skeleton; the facts under them are in `<settings primary_language>`. Preserve user-customized headers verbatim.
+Output language: `identity/profile.md` and `identity/*.md` are Policy B — see `<output_language_policy>`. Template H2 headers stay English skeleton; the facts under them are in `<settings primary_language>`. Preserve user-customized headers verbatim.
 
 `identity/profile.md` stores the user's identity, preferences, and learned behavioral patterns. It is injected into every agent session via `<user>` tags — keep it concise (target: under ~600 tokens total).
 
-Detailed, dictionary-like background belongs under `user/*.md`. Read `identity/_index.md` first, then fetch only the topic file you need.
+Detailed, dictionary-like background belongs under `identity/*.md`. Read `identity/_index.md` first, then fetch only the topic file you need.
 
 ## When to Update
 
@@ -37,34 +37,24 @@ Detailed, dictionary-like background belongs under `user/*.md`. Read `identity/_
 - "user has been unusually curt over the last week" — a pattern inferred across multiple turns with no single user statement. Written to `profile.md ## Learned Context` by Evening Review Step 3a only; the DM handler and sweep do not write inferred patterns.
 - "my sister just had a baby" → `identity/people.md ## Family`. If the section doesn't exist yet (fresh topic file with only the H1), the PATCH returns `section_not_found` — retry with `mode: "append_to_file"` and include `"\n## Family\n- <bullet>"` in `content`. The next write to that section succeeds normally.
 
-The decision rule (profile.md vs `user/<topic>.md` tie-breakers, `section_not_found` → `append_to_file` first-write fallback, and the read-before-write `curl` recipe) is documented in full in this skill — see §"Section ownership", §"File schema", and §"Worked example" below.
+The decision rule (profile.md vs `identity/<topic>.md` tie-breakers, `section_not_found` → `append_to_file` first-write fallback, and the read-before-write `curl` recipe) is documented in full in this skill — see §"Section ownership", §"File schema", and §"Worked example" below.
 
 ## Section ownership
 
-| Section | Update trigger | Who writes |
-|---|---|---|
-| Identity | Explicit statement | DM handler, sweep |
-| Work Pattern | Explicit statement | DM handler, sweep |
-| Platforms | Explicit statement | Setup, explicit change |
-| Expertise | Explicit statement (summary) | DM handler, sweep |
-| Notification Preferences | Explicit statement | DM handler, sweep |
-| Learned Context | Stated preferences (DM) + Raw Signals graduation (evening) | DM handler, sweep, Evening Review 3a |
-| Raw Signals | Behavioral detection | SignalDetector only |
-| `user/<topic>.md` (people / work / expertise / personal / goals) | Any detail-heavy fact per the capture decision rule in the DM task-flow | DM handler, `routine.user_profile_sweep` |
+Per-section trigger → destination → writer is in the auto-curated **When-to-update routing** block below. Writer notes layered on top:
 
-"DM handler" above covers both `message.received.dm` and `message.received.dm_first`. "Sweep" is `routine.user_profile_sweep` (fires 03:50 and 17:50 local; see its task-flow). Evening Review Step 3a is an additional writer to Learned Context only, synthesizing entries from Raw Signals graduation.
+- "DM handler" covers both `message.received.dm` and `message.received.dm_first`. "Sweep" is `routine.user_profile_sweep` (fires 03:50 and 17:50 local; see its task-flow). Evening Review Step 3a is an additional writer to Learned Context only, synthesizing entries from Raw Signals graduation.
+- **Do not write to Raw Signals from other events — that section is `SignalDetector`'s alone.**
 
-**Do not write to Raw Signals from other events — that section is `SignalDetector`'s alone.**
+## identity/profile.md vs identity/<topic>
 
-## user/profile.md vs user/
+**identity/profile.md** — injected every session: Identity, Work Pattern, Platforms, Expertise summary, Notification Preferences, Learned Context.
 
-**user/profile.md** — injected every session: Identity, Work Pattern, Platforms, Expertise summary, Notification Preferences, Learned Context.
-
-**user/*.md** — dictionary-like (`people` | `work` | `expertise` | `goals` | `personal`), too detailed for every session. Read `_index.md` first → fetch only the relevant topic.
+**identity/*.md** — dictionary-like (`people` | `work` | `expertise` | `goals` | `personal`), too detailed for every session. Read `identity/_index.md` first → fetch only the relevant topic. Per-topic ownership is in the auto-curated **Knowledge map** block below.
 
 ## File schema
 
-All `user/*.md` files must keep YAML frontmatter with `type: user`,
+All `identity/*.md` files must keep YAML frontmatter with `type: user`,
 `owner: shared`, and `updated: YYYY-MM-DD`, followed by an H1. When using
 section-level PATCH, preserve the existing frontmatter. When doing a
 full-file PUT, update `updated` to today's date.
@@ -106,7 +96,7 @@ If the user says "I don't want work notifications on weekends", paraphrase into
 preferences are NOT profile content.** Route them to the `character`
 runtime-config field via `PATCH /api/config/character` (narrow
 endpoint, 1000-char cap, read-before-write). Never write tone /
-style preferences into `identity/profile.md` or any `user/*.md`.
+style preferences into `identity/profile.md` or any `identity/*.md`.
 
 Full recipe — triggers, merge rules, endpoint note, cap-handling, and
 where the value ends up — is in the character-preferences reference
@@ -120,7 +110,7 @@ See _safety.md "Common Patterns" for the general rule. Section name in PATCH is
 
 ### Worked example
 
-User: `"I want to read 20 books this year."` → GET user/profile.md (or topic file), merge new bullet into the right section. For a top-level goal summary bullet:
+User: `"I want to read 20 books this year."` → GET identity/profile.md (or topic file), merge new bullet into the right section. For a top-level goal summary bullet:
 ```bash
 curl -s -X PATCH http://localhost:8321/api/context/identity/profile \
   -H 'Content-Type: application/json' \
@@ -130,7 +120,7 @@ For a full-section replace, GET first, merge with existing bullets, then PATCH w
 
 **WRONG** (erases existing bullets): `curl -s -X PATCH ... -d '{"section": "learned_context", "mode": "replace", "content": "- [2026-04-23] Reading goal: ..."}'` when the section already held other bullets.
 
-For writes to `user/<topic>.md` (people / work / expertise / personal / goals), the same decision rule applies — §"Routing edge cases" above documents the `section_not_found` → `append_to_file` first-write fallback (with a worked `curl` example against `identity/people.md`). The read-before-write rule applies identically when merging into an existing `user/<topic>.md` section.
+For writes to `identity/<topic>.md` (people / work / expertise / personal / goals), the same decision rule applies — §"Routing edge cases" above documents the `section_not_found` → `append_to_file` first-write fallback (with a worked `curl` example against `identity/people.md`). The read-before-write rule applies identically when merging into an existing `identity/<topic>.md` section.
 
 ## Learned Context entry format
 
@@ -150,7 +140,7 @@ Review can prune entries older than 30 days:
 - **Silent updates.** Never notify the user about profile changes.
 - **Keep concise.** 2–5 bullets per section max. Consolidate similar bullets.
 - **No duplicates.** Scan before adding. Prefer refining an existing bullet.
-- **Total budget ~600 tokens** for user/profile.md. Consolidate aggressively.
+- **Total budget ~600 tokens** for identity/profile.md. Consolidate aggressively.
 - **Don't write verbatim user messages.** Paraphrase into stable preference statements.
 
 ## Initial Setup
@@ -166,7 +156,7 @@ Populate `identity/profile.md` (Identity, Work Pattern, Platforms, Expertise sum
 The generic GET / PATCH surface (modes, fields, error envelopes) is
 documented in the **context** skill `references/api.md`. user-profile
 writes target the two paths `/api/context/identity/profile` (the injected
-summary file) and `/api/context/user/:topic` (one of `people` /
+summary file) and `/api/context/identity/:topic` (one of `people` /
 `work` / `expertise` / `personal` / `goals`).
 
 Two user-profile-specific notes layered on top of the generic surface:

package/agent-assets/skills/user-profile/curation.json

@@ -6,8 +6,8 @@
       "kind": "knowledge_layout",
       "anchor": "<!-- CURATION:knowledge_layout id=\"topic-files\" -->",
       "human_label": "Topic file layout",
-      "description": "Which user/* file owns which kind of fact",
-      "scope_paths": ["identity/profile.md", "user/*.md"]
+      "description": "Which identity/* file owns which kind of fact",
+      "scope_paths": ["identity/profile.md", "identity/*.md"]
     },
     {
       "id": "routing-table",
@@ -15,7 +15,7 @@
       "anchor": "<!-- CURATION:routing_table id=\"routing-table\" -->",
       "human_label": "When-to-update routing rules",
       "description": "Trigger phrases mapped to destination file, section, and write mode",
-      "scope_paths": ["user/*.md"]
+      "scope_paths": ["identity/*.md"]
     },
     {
       "id": "learned-context-format",

package/agent-assets/skills/user-profile/references/character-preferences.md

@@ -10,7 +10,7 @@ description: Tone / style / voice / language preferences are agent directives
 are NOT profile content** — they are agent directives, not user facts.
 Route them to the `character` runtime-config field via `PATCH
 /api/config/character` (see `docs/design/15-character.md`), never to
-`identity/profile.md` or any `user/*.md`.
+`identity/profile.md` or any `identity/*.md`.
 
 ## Triggers
 
@@ -78,6 +78,6 @@ uniformly — no separate injection per backend.
 ## What does NOT belong here
 
 Facts about the user — identity, role, expertise, hobbies, people,
-goals — go to `identity/profile.md` or `user/<topic>.md`, not to
+goals — go to `identity/profile.md` or `identity/<topic>.md`, not to
 `character`. The split is: `character` says *how* the agent speaks;
-`user/*` says *who the user is*.
+`identity/*` says *who the user is*.

package/agent-assets/skills/wiki/wiki-ask/SKILL.md

@@ -9,7 +9,7 @@ allowed-tools:
 
 You run under process key `wiki.ask`.
 
-Read `<wiki_command>` for the user's `question`. Search and read relevant `20_wiki/` notes first; read `10_raw/` only when the wiki notes need source verification.
+Read `<wiki_command>` for the user's `question`. Search and read relevant `20_wiki/` notes first (see wiki-vault-rules for `/search` and `/index`); read `10_raw/` only when the wiki notes need source verification.
 
 Write the answer to:
 

package/agent-assets/skills/wiki/wiki-compile/SKILL.md

@@ -26,7 +26,7 @@ Therefore:
 | Method | Path | Purpose |
 |---|---|---|
 | `GET`   | `/api/wiki/{{workspace_name}}/index` | List every file in the workspace with `path`/`mtime`/`sizeBytes`. Primary enumeration tool. |
-| `GET`   | `/api/wiki/{{workspace_name}}/search?q=<query>` | Body-substring search for duplicate detection. |
+| `GET`   | `/api/wiki/{{workspace_name}}/search?q=<query>` | Duplicate detection. Defaults to FTS5 token matching; append `&kind=grep` for literal substring matches. |
 | `GET`   | `/api/wiki/{{workspace_name}}/files/<path>` | Read raw notes, existing wiki notes, taxonomy, log. |
 | `POST`  | `/api/wiki/{{workspace_name}}/files/20_wiki/<slug>.md` | Create a new wiki note. |
 | `POST`  | `/api/wiki/{{workspace_name}}/files/20_wiki/<slug>.md` | Rewrite an existing wiki note — re-POST to the same path overwrites in place (a `.snapshots/` backup is taken first). |
@@ -93,7 +93,7 @@ Inside `<<'JSON'` (single-quoted marker) the body is verbatim — only JSON's ow
 ## Anti-patterns (silent denials — never claim success after these)
 
 - `Write` / `Edit` tools — **stripped from the session allow-list** for every `wiki.*` process key. The SDK denies them silently under `dontAsk` ("Permission to use Write has been denied …"). There is no path-rewrite that makes them work; use the Wiki API via curl. The agent that hit "Write denied → reported failure" is the canonical failure mode this section exists to prevent.
-- `Bash(find ...)`, `Bash(ls ...)`, `Bash(cat ...)`, `Bash(grep ...)`, `Bash(wc ...)`, and every other shell utility — silently denied. Only `Bash(curl *)` and `Bash(jq *)` are on the allow-list. Enumerate via `GET /api/wiki/<ws>/index`, not from disk.
+- `Bash(find ...)`, `Bash(ls ...)`, `Bash(cat ...)`, `Bash(grep ...)`, `Bash(wc ...)`, and every other shell utility — silently denied. Only `Bash(curl *)` and `Bash(jq *)` are on the allow-list (`jq` runs standalone or as `curl … | jq`). Enumerate via `GET /api/wiki/<ws>/index`, not from disk.
 - `echo '{...}' | curl ...`, `cat <<JSON | curl ... -d @- JSON`, `bash -c "curl ..."`, `( curl ... )`, `var=... curl ...`, `curl ... ; curl ...` — Bash command does not start with `curl`; silently denied. The reverse — `curl ... -d @- <<'JSON' … JSON` on the same line — DOES start with `curl` and IS allowed (the heredoc redirects into curl's stdin).
 - `curl ... -d @/some/path` — `@<filepath>` is blocked by the security hook and the shim. The only acceptable `@…` value is the literal stdin marker `@-`.
 - `curl http://example.com/...` (non-loopback) — only `http://localhost:8321/api/*` is permitted.
@@ -104,10 +104,11 @@ Inside `<<'JSON'` (single-quoted marker) the body is verbatim — only JSON's ow
 
 | Status | Body code | Cause | Recovery |
 |---|---|---|---|
-| 400 | `invalid_body` | JSON body did not parse / `content` not a string | Switch to the heredoc shape if you were inline-escaping a multi-KB body. |
+| 400 | `invalid_json_body` | JSON body did not parse (checked first, before Zod) | Switch to the heredoc shape if you were inline-escaping a multi-KB body. |
+| 400 | `invalid_body` | Body parsed but `content` is not a string (Zod rejection) | Ensure `content` is a JSON string. |
 | 400 | `invalid_path` / `invalid_layer` | Slug shape or layer prefix rejected | Path must be exactly `20_wiki/<slug>.md`. Slug matches `^[a-z0-9][a-z0-9-]*$`. |
 | 403 | `missing_process_key` | Header missing | Add `-H 'x-process-key: wiki.compile'`. |
-| 403 | `wiki_write_denied` | Trying to write outside `20_wiki/` (or the `_index.md` / `log.md` exceptions) under `wiki.compile` | Fix the target path. Use `wiki-graduate` for inbox-to-wiki promotion (same process key, different source layer). |
+| 403 | `wiki_write_denied` | A non-`wiki.compile` key targeting the `20_wiki` layer. `_index.md` is a normal `20_wiki` file; `log.md` is its own append-only layer (PATCH-only). | Fix the target path. Use `wiki-graduate` for inbox-to-wiki promotion (same process key, different source layer). |
 | 409 | `append_only` | POST to an existing `10_raw/` file or `log.md` (those two layers are create-only). Does NOT apply to `20_wiki/<slug>.md` — re-POSTing there overwrites in place. | For `log.md` use `PATCH mode: "append"`. `10_raw/` files cannot be overwritten by design. |
 | 413 | — | Body exceeds 512 KB | Split the note or trim verbatim extracts. |
 | 5xx | — | Daemon error | Append a failure line to `log.md`, classify the run as partial, do not retry inside the same turn. |

package/agent-assets/skills/wiki/wiki-connect/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wiki-connect
-description: Load for wiki.connect. Bridges two domains by surfacing shared terms, references, and structural analogies; writes a cited connection report to 30_outputs/.
+description: Bridge two wiki domains on /connect A B — surface shared terms, common references, and structural analogies, then write a cited connection report to 30_outputs/. Runs under process key wiki.connect.
 allowed-tools:
   - Bash(curl *)
 ---
@@ -11,6 +11,16 @@ You run under process key `wiki.connect`.
 
 Read `<wiki_command>` for the two topics — fields `topic_a` and `topic_b`. Your job is to find genuine bridges between the two domains using only what the wiki contains. Speculative analogies are out of scope; if there is no real overlap, say so plainly.
 
+## Endpoints
+
+Every request includes `-H 'x-process-key: wiki.connect'`. Body shapes:
+
+| Method | Path | Body |
+|---|---|---|
+| `GET`   | `/api/wiki/{{workspace_name}}/search?q=<topic>` | — |
+| `POST`  | `/api/wiki/{{workspace_name}}/files/30_outputs/<file>.md` | `{"content":"<report-md>"}` |
+| `PATCH` | `/api/wiki/{{workspace_name}}/files/log.md` | `{"mode":"append","content":"<line>\n"}` |
+
 ## Method
 
 1. Search each topic independently:
@@ -30,11 +40,18 @@ Read `<wiki_command>` for the two topics — fields `topic_a` and `topic_b`. You
 
 Write exactly one report:
 
-```
-POST /api/wiki/{{workspace_name}}/files/30_outputs/<YYYY-MM-DD>-connect-<slug>.md
-x-process-key: wiki.connect
+```bash
+curl http://localhost:8321/api/wiki/{{workspace_name}}/files/30_outputs/<YYYY-MM-DD>-connect-<slug>.md \
+  -X POST \
+  -H 'content-type: application/json' \
+  -H 'x-process-key: wiki.connect' \
+  -d @- <<'JSON'
+{"content":"<report-md>"}
+JSON
 ```
 
+The body is `{"content":"<report-md>"}` — `wikiFilePostSchema` requires the `content` field. An empty body returns `400 invalid_json_body`; valid JSON missing `content` returns `400 invalid_body`. Always send the `content` field.
+
 - `<YYYY-MM-DD>` is today's date.
 - `<slug>` is `<slug-a>--<slug-b>` using the canonical slugs from `90_meta/taxonomy.md` when available, kebab-cased and joined by a double hyphen.
 
@@ -59,7 +76,17 @@ Report shape:
 - proposed wiki slug, one-sentence rationale, suggested anchor notes
 ```
 
-If no genuine bridges exist, write the report anyway with empty sections marked `_(none)_` and a `## Summary` that names that clearly — a "no connection" finding is still useful to the owner. Append a one-line `log.md` entry referencing the output filename and both topics.
+If no genuine bridges exist, write the report anyway with empty sections marked `_(none)_` and a `## Summary` that names that clearly — a "no connection" finding is still useful to the owner.
+
+Then append a one-line `log.md` entry referencing the output filename and both topics. `log.md` is append-only — POST to an existing `log.md` returns `409 'Use PATCH to append log.md'`. Use PATCH:
+
+```bash
+curl http://localhost:8321/api/wiki/{{workspace_name}}/files/log.md \
+  -X PATCH \
+  -H 'content-type: application/json' \
+  -H 'x-process-key: wiki.connect' \
+  -d '{"mode":"append","content":"[<ISO>] wiki.connect: <topic_a> ↔ <topic_b> → 30_outputs/<file>.md\n"}'
+```
 
 ### Completion message (mandatory)
 

package/agent-assets/skills/wiki/wiki-ingest/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wiki-ingest
-description: Load for wiki.ingest_url. Captures one URL into 10_raw/<slug>.md by POSTing through the daemon Wiki API. Carries the canonical curl invocation, the path / response contract, and the strict success-verification rule.
+description: Load for wiki.ingest_url. Use when ingesting one shared URL/article into the wiki raw layer (10_raw) via the daemon Wiki API. Carries the canonical curl invocation, the path / response contract, and the strict success-verification rule.
 allowed-tools:
   - WebFetch
   - Bash(curl *)
@@ -47,7 +47,7 @@ Do NOT call any other daemon endpoint. The daemon has **no** `/api/send-message`
    - `## Source extracts` — verbatim or close-paraphrase quotes.
    - `## Open questions` — anything you could not verify from the page.
 4. **POST the note** via the canonical curl shape (next section). Inspect the response body.
-5. **Verify**: the response body must be exactly `{"ok":true,"path":"10_raw/<slug>.md"}`. If anything else (4xx/5xx, missing `ok`, wrong path, no body, `PA_API_ERROR …` on stderr), treat it as failure. Follow the error table below or PATCH `log.md` and emit the failure DM.
+5. **Verify**: the response body must be exactly `{"ok":true,"path":"10_raw/<slug>.md"}`. If anything else (4xx/5xx, missing `ok`, wrong path, no body, `PA_API_ERROR …` on stderr), treat it as failure. Follow the error->recovery table in "Curl mechanics" or PATCH `log.md` and emit the failure DM.
 6. **Emit the completion DM** (last section). Success or failure, exactly one line, no extra prose.
 
 ## Path shape — exact, no nesting
@@ -119,59 +119,15 @@ curl http://localhost:8321/api/wiki/{{workspace_name}}/files/log.md \
   -d '{"mode":"append","content":"[2026-05-13T05:08:00Z] wiki.ingest_url failed https://news.example.com/path/123 — fetch returned 403\n"}'
 ```
 
-## Body-quoting rules
+## Curl mechanics, anti-patterns, and error recovery
 
-**Heredoc body (recommended for article bodies):** wrap with a single-quoted marker (`<<'JSON' … JSON`). The body is verbatim — shell does NOT expand `$`, backticks, or quotes. Only JSON's own escapes apply: `\"`, `\\`, `\n`. The line `JSON` must appear at column 0 with no trailing characters.
+Body-quoting rules, the silent-denial anti-patterns, and the per-status error->recovery table live on demand:
 
-**Inline body (short bodies only):** wrap the JSON in outer single quotes; inside, use JSON escapes:
-
-| Need in `content` | Write in shell-arg |
-|---|---|
-| `"` | `\"` |
-| `\` | `\\` |
-| newline | `\n` |
-| `'` | `'\''` (close-escape-reopen), or substitute `’` (U+2019) |
-| `$`, backticks | leave as-is (single quotes suppress expansion) |
-
-Keep the note compact — well under 512 KB. Curate 5-20 KB of the most informative extracts rather than dumping the whole page.
-
-## Anti-patterns (silent denials / 4xx — never claim success after these)
-
-- `WebFetch http://localhost:8321/...` — Claude WebFetch refuses loopback. Use curl.
-- `echo '{...}' | curl ...`, `cat <<JSON | curl ... -d @- JSON ; …`, `bash -c "curl ..."` — Bash command does not start with `curl`; denied silently under `dontAsk`. (Heredoc redirected directly into curl on the same line — `curl ... -d @- <<'JSON' … JSON` — IS allowed because the command still starts with `curl`.)
-- `curl ... -d @/tmp/body.json` — `@<path>` form is blocked by the security hook and by the shim.
-- `curl http://example.com/...` (non-loopback) — security hook denies; only `http://localhost:8321/api/*` is permitted.
-- POST to a non-existent path like `/api/send-message`, `/api/whatsapp/send`, `/api/notify-user`, `/api/dm`. These are NOT daemon routes; calls return 401/404 and DO NOT notify anyone.
-- POST/PATCH to `/api/wiki/.../10_raw/<slug>.md` a second time — raw is create-only; the second call returns 409 and **does NOT** modify the file.
-- `Write` / `Edit` tools — stripped from the session allow-list for every `wiki.*` process key. The SDK denies them silently under `dontAsk` (you'll see "Permission to use Write has been denied …"). There is no path-rewrite that makes them work; use the Wiki API via curl. `Bash(find ...)`, `Bash(ls ...)`, `Bash(cat ...)` and other shell utilities are also denied — only `Bash(curl *)` and `Bash(jq *)` are on the allow-list.
-
-## Troubleshooting
-
-Every non-2xx response causes the curl shim to write one line to stderr:
-
-```
-PA_API_ERROR {"method":"POST","path":"/api/wiki/...","status":<n>,"bodyPreview":"<json error>"}
-```
-
-Read `status` + `bodyPreview` and react:
-
-| Status | Body code | Cause | Recovery |
-|---|---|---|---|
-| 200 | (response is `{"ok":true,"path":...}`) | Success | Emit the success DM. |
-| 200 | (response missing `ok` or `path`) | Should not happen — but if it does, treat as failure | Emit failure DM. |
-| 400 | `invalid_body` | JSON body did not parse / `content` not a string | Re-emit the body. For inline `-d` check your single-quote / `\n` / `\"` escapes. If the body was `@-` literally, the heredoc was missed — switch to the heredoc shape (`-d @- <<'JSON' … JSON` on the same line as curl). |
-| 400 | `invalid_path` / `invalid_layer` | Slug or layer rejected | Path must be **exactly** `10_raw/<slug>.md`, slug matching `^[a-z0-9][a-z0-9-]*$`. No nested folders. |
-| 403 | `missing_process_key` | Header missing | Add `-H 'x-process-key: wiki.ingest_url'` and retry. |
-| 403 | `raw_write_denied` | Process key isn't `wiki.ingest_url` | Configuration error; emit failure DM, do not retry. |
-| 409 | `append_only` | Slug already exists in `10_raw/` | Suffix the slug (`<slug>-2`), retry the POST **once**. If `-2` also 409, PATCH log.md and emit failure DM — do not loop further. |
-| 413 | (body too large) | Article > 512 KB | Trim verbatim extracts; keep essentials. |
-| 5xx | — | Daemon error | PATCH log.md and emit failure DM. Do not retry — the daemon will not heal mid-turn. |
-
-If the Bash call returns to the prompt with **no stdout body and no `PA_API_ERROR`**, your command did not start with literal `curl` and was silently denied. Rewrite it as a flat, single-line curl invocation following the canonical shape above.
+{{> ref:curl-errors }}
 
 ## Completion message (mandatory final assistant text)
 
-Emit exactly one line as your final assistant message. The daemon forwards this verbatim to the channel the bang came from — no other delivery mechanism is needed and you must NOT try to "send" it through another endpoint.
+Emit exactly one line as your final assistant message. The daemon forwards this verbatim to the channel the bang came from — no other delivery mechanism is needed and you must NOT try to "send" it through another endpoint (no /api/send-message etc.; see "Allowed endpoints").
 
 - Success (only after seeing `{"ok":true,"path":"10_raw/<slug>.md"}`): `Ingested <url> → 10_raw/<slug>.md`
 - Failure (any other outcome): `Failed <url> — <one-sentence reason>`