@aitne-sh/aitne 0.1.7 → 0.1.9

package/agent-assets/skills/today/seeds/section-shape.seed.json

@@ -2,7 +2,7 @@
   "kind": "knowledge_layout",
   "files": [
     {
-      "path": "today.md",
+      "path": "state/today.md",
       "purpose": "today's plan, schedule, agent log, and handoff to tomorrow",
       "sections": [
         { "heading": "## Plan", "contains": "the day's intent in plain prose" },

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

@@ -16,12 +16,12 @@ morning briefing). This skill is how every callsite touches that queue.
 
 ## Source-of-truth file
 
-**`agent/profile-questions.md`** — agent-internal markdown. Three
+**`state/profile-questions.md`** — agent-internal markdown. Three
 top-level sections: `## Pending`, `## In Progress`, `## Answered`.
 Never auto-injected into prompts; load only when this skill is in use.
 
 ```bash
-curl -s http://localhost:8321/api/context/agent/profile-questions
+curl -s http://localhost:8321/api/context/state/profile-questions
 ```
 
 ### Pending row format
@@ -34,7 +34,7 @@ curl -s http://localhost:8321/api/context/agent/profile-questions
 |---|---|
 | `PRIO`        | `HIGH` / `MID` / `LOW` — selection priority |
 | `<id>`        | snake_case unique. Doubles as the correlation id in any scheduled DM description (`profile_interview:<id> — <hint>`) |
-| `target_path` | which user file the answer should land in, e.g. `user/profile.md` |
+| `target_path` | which user file the answer should land in, e.g. `identity/profile.md` |
 | `## Section`  | optional — narrows to a section within the target file |
 | `match=<anchor>` | optional — bullet key (English, like `Name`, `Timezone`, `Sleep`, `Working hours`). Required when multiple rows share a section, or when setup pre-seeds the section with an unrelated bullet |
 | `ask-hint`    | English brief of WHAT to ask (agent-internal, Policy A). Render the actual DM per `<output_language_policy>` — this skill intentionally splits the two surfaces |
@@ -101,38 +101,13 @@ curl -s "http://localhost:8321/api/profile-questions/slot-filled?path=user/profi
 This wraps the canonical TS helper. Use it — do NOT re-derive the rule
 in prose. URL-encode `section` and `anchor` if they contain spaces.
 
-## Operation 1 — Pick a question (morning routine Step 7.5)
+## Operation 1 — Pick a question (Morning Routine Step 7.5)
 
-```
-1. GET agent/profile-questions.md.
-2. Skip the entire step if any of:
-     - ## In Progress is non-empty.
-     - ## Pending is empty.
-     - User has not sent a DM in the last 24h.
-     - Day-type focus for [personal] on line 2 of <today> is `off`.
-     - The current run is the initial morning routine
-       (`routine.morning_routine_initial`) — it lands during setup; piling
-       on a question is bad UX.
-3. Walk Pending rows in priority order (HIGH → MID → LOW, then file
-   order). For each candidate:
-     a. If the row carries `<!-- last_attempted=YYYY-MM-DD -->` and that
-        date is within the last 7 days, skip — cooldown.
-     b. Call /api/profile-questions/slot-filled for the row's target. If
-        the slot turns out to be filled (Layer 2 catches drift since
-        last sweep), tick the row [x] (read-rebuild + replace) and
-        append `- [x] <today> → <id> (reconciled:morning)` to ## Answered.
-        Continue to the next candidate.
-     c. Otherwise, this is the chosen row. Stop walking.
-4. Append a single line to today.md ## Agent Notes (latent-question
-   flavor, see "Today.md surfacing" below):
-     `- Profile question (latent): <id> — wait for natural opportunity`
-5. Append to ## In Progress in the queue file (PATCH replace, read-rebuild):
-     `- <id> :: state=latent :: since=<today>`
-   The `since=` date is load-bearing — the evening sweep needs it to
-   compute the 3-day fallback threshold.
-6. Do NOT POST /api/schedule for this row. Latent rows are NOT
-   scheduled DMs — they wait for an opportunity.
-```
+Morning-routine-only. The full skip gates (5 conditions), walk order,
+drift-tick recovery, today.md mirror line, and no-schedule rule are in
+the op-morning reference below.
+
+{{> ref:op-morning }}
 
 ## Operation 2 — Latent opportunity check (DM handler)
 
@@ -175,11 +150,11 @@ composing the reply.
      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/agent/profile-questions` section=in_progress
+        - `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/today` section=agent_notes — replace the
+        - `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.
@@ -190,34 +165,12 @@ composing the reply.
 
 ## Operation 3 — Latent piggyback (morning briefing composition)
 
-Mirror of Operation 2, run inside the `## Morning briefing` sub-flow of
-`scheduled.dm.md`. The briefing is already an outgoing DM the agent
-composes; it is one of the few naturally-occurring opportunities to
-slip in a question.
+Scheduled.dm-only. Mirror of Operation 2 but run inside the
+`## Morning briefing` sub-flow of `scheduled.dm.md`. Slot-filled
+pre-check, domain-overlap judgment, and the two PATCHes are in the
+op-briefing reference below.
 
-```
-1. GET agent/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 `filled: true`, resolve
-   the row (tick Pending, remove In Progress, append
-   `- [x] <today> → <id> (reconciled:opportunity)` to Answered, remove
-   the matching `Profile question (latent):` line from today.md ## Agent Notes) and
-   skip the piggyback — DO NOT weave the question.
-3. Decide whether the briefing's main content overlaps with the
-   question's domain (work questions when the day is calendar-heavy
-   with work meetings; personal questions when the day is light /
-   personal). If yes, weave one question into the briefing as a closing
-   side note. Same naturalness rules as Operation 2 — no preamble, no
-   separate paragraph.
-4. After composing, issue two PATCH replaces (separate calls):
-   - `PATCH /api/context/agent/profile-questions` section=in_progress —
-     flip the entry to
-     `state=asked :: since=<unchanged> :: asked_at=<current_time>`.
-   - `PATCH /api/context/today` section=agent_notes — flip the matching
-     `Profile question (latent):` line by changing the parenthetical to
-     `(asked HH:MM)`.
-```
+{{> ref:op-briefing }}
 
 ## Operation 4 — Capture the answer (DM handler queue reconcile)
 
@@ -278,7 +231,7 @@ The heuristic anchor lookup matches against bullet keys written by the
 - Sleep: 23:00–07:00
 ```
 
-Anchors in `agent/profile-questions.md` MUST match these English keys —
+Anchors in `state/profile-questions.md` MUST match these English keys —
 not the user's primary-language phrasing. If a future `user-profile`
 schema change introduces non-English keys, Layers 1–3 silently miss
 those bullets and the system degrades to Layer-4-only protection
@@ -302,20 +255,23 @@ those bullets and the system degrades to Layer-4-only protection
 
 ```bash
 # Read the queue
-curl -s http://localhost:8321/api/context/agent/profile-questions
+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"
 
 # Section-level edit (queue file uses the standard context API)
-curl -s -X PATCH http://localhost:8321/api/context/agent/profile-questions \
+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","description":"profile_interview:<id> — <hint>","model":"sonnet","taskContext":{"scheduledBy":"user_profile_sweep_fallback","queueId":"<id>","importance":"low"}}'
+  -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"}}'
 ```
 
 The PATCH `section` argument is snake_case of the heading: `pending`,

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

@@ -0,0 +1,51 @@
+---
+kind: reference
+name: op-briefing
+description: Operation 3 — weave a latent profile question into the morning briefing inside scheduled.dm's ## Morning briefing sub-flow. Slot-filled pre-check, domain overlap, two PATCHes.
+---
+
+# Operation 3 — Latent piggyback (morning briefing composition)
+
+Run this inside the `## Morning briefing` sub-flow of
+`scheduled.dm.md`. The briefing is already an outgoing DM the agent
+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.
+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
+   `filled: true`, resolve the row (tick Pending, remove In Progress,
+   append `- [x] <today> → <id> (reconciled:opportunity)` to Answered,
+   remove the matching `Profile question (latent):` line from
+   today.md ## Agent Notes) and skip the piggyback — DO NOT weave the
+   question.
+3. Decide whether the briefing's main content overlaps with the
+   question's domain (work questions when the day is calendar-heavy
+   with work meetings; personal questions when the day is light /
+   personal). If yes, weave one question into the briefing as a
+   closing side note. Same naturalness rules as Operation 2 — no
+   preamble, no separate paragraph.
+4. After composing, issue two PATCH replaces (separate calls):
+   - `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 — flip the
+     matching `Profile question (latent):` line by changing the
+     parenthetical to `(asked HH:MM)`.
+```
+
+## What "natural piggyback" means in this sub-flow
+
+The briefing already enumerates today's calendar items, deltas since
+yesterday, and any flagged inbound from the overnight window. A
+piggyback question should feel like a side comment on one of those —
+"the design review is at 14:00 — what's your usual ramp-up before
+those?" — not a separate `## Question:` paragraph.
+
+If the briefing's main content does not have any natural anchor for
+the latent question's domain, do not force it. Leave the entry
+`state=latent` and let Operation 2 catch it on the next DM the user
+sends.

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

@@ -0,0 +1,59 @@
+---
+kind: reference
+name: op-morning
+description: Operation 1 — pick a profile-interview question during Morning Routine Step 7.5. Skip gates, walk order, drift-tick recovery, today.md mirror, no-schedule rule.
+---
+
+# Operation 1 — Pick a question (Morning Routine Step 7.5)
+
+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
+Operation 2 / 3 / 4 instead.
+
+```
+1. GET agent/profile-questions.md.
+2. Skip the entire step if any of:
+     - ## In Progress is non-empty.
+     - ## Pending is empty.
+     - User has not sent a DM in the last 24h.
+     - Day-type focus for [personal] on line 2 of <today> is `off`.
+     - This is the first-run morning routine (`<yesterday>` is absent
+       from your prompt context — the wizard just finished setup and a
+       profile question on day 1 piles onto an already busy onboarding
+       surface). Pre-Phase-4 this was keyed off the
+       `routine.morning_routine_initial` process key, which the
+       dispatcher no longer emits — both branches now route through
+       `routine.morning_routine` and the cue is `<yesterday>` absence.
+3. Walk Pending rows in priority order (HIGH → MID → LOW, then file
+   order). For each candidate:
+     a. If the row carries `<!-- last_attempted=YYYY-MM-DD -->` and
+        that date is within the last 7 days, skip — cooldown.
+     b. Call /api/profile-questions/slot-filled for the row's target.
+        If the slot turns out to be filled (Layer 2 catches drift
+        since last sweep), tick the row [x] (read-rebuild + replace)
+        and append `- [x] <today> → <id> (reconciled:morning)` to
+        ## Answered. Continue to the next candidate.
+     c. Otherwise, this is the chosen row. Stop walking.
+4. Append a single line to today.md ## Agent Notes (latent-question
+   flavor, see "Today.md surfacing" in the skill body):
+     `- Profile question (latent): <id> — wait for natural opportunity`
+5. Append to ## In Progress in the queue file (PATCH replace,
+   read-rebuild):
+     `- <id> :: state=latent :: since=<today>`
+   The `since=` date is load-bearing — the evening sweep needs it to
+   compute the 3-day fallback threshold.
+6. Do NOT POST /api/schedule for this row. Latent rows are NOT
+   scheduled DMs — they wait for an opportunity.
+```
+
+## Why no schedule?
+
+A cold scheduled DM that asks "what's your timezone?" out of nowhere
+is exactly the failure mode the queue exists to avoid. The latent row
+sits in `## In Progress` until either Operation 2 (DM-handler
+opportunity match) or Operation 3 (morning briefing piggyback)
+naturally weaves it in. Only the evening sweep's Operation 5B fallback
+(3 days latent without an opportunity, user still active) escalates to
+a scheduled DM — and that's the design's safety valve, not the
+primary path.

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

@@ -30,10 +30,18 @@ B. LATENT FALLBACK PROMOTION.
        state=scheduled. Register POST /api/schedule with:
          {time: tomorrow @ 14:00 local (or quiet_hours_end + 2h),
           taskType: "dm_session",
+          prompt: "profile_interview:<id> — run Operation 6 (the
+                   scheduled.dm ## Profile interview sub-flow): fire-time
+                   slot-filled abort check, then compose one short natural
+                   DM around <ask-hint>.",
           description: "profile_interview:<id> — <ask-hint>",
-          model: "sonnet",
+          tier: "medium",
           taskContext: {scheduledBy: "user_profile_sweep_fallback",
                         queueId: "<id>", importance: "low"}}
+       NOTE: `prompt` is REQUIRED by POST /api/schedule (the wake-up
+       session has NO memory — the prompt is its only instruction).
+       `description` is the short list label whose `profile_interview:<id>`
+       prefix triggers Operation 6; keep both fields.
        Update the In Progress entry to
        `state=scheduled :: since=<unchanged> :: scheduled_at=<tomorrow 14:00>`.
        Remove the matching `Profile question (latent): <id>` line from

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

@@ -8,26 +8,21 @@ allowed-tools:
 
 # User Profile Update Guide
 
-Output language: follow `<output_language_policy>`. `user/profile.md`
-and `user/*.md` are Policy B — template H2 headers (`## Identity`,
-`## Work Pattern`, `## Platforms`, `## Expertise`, `## Notification
-Preferences`, `## Learned Context`, `## Raw Signals`) are skeleton and
-stay English; the facts you write under them are in
-`<settings primary_language>`. Preserve user-customized headers verbatim.
+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.
 
-`user/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).
+`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 `user/_index.md` first, then fetch only the topic file you need.
+Detailed, dictionary-like background belongs under `user/*.md`. Read `identity/_index.md` first, then fetch only the topic file you need.
 
 ## When to Update
 
 **Immediately (same turn) when the user shares:**
 - Identity or role — "I'm a …", "I work at …", "my title is …" → `profile.md ## Identity`
-- People they know — names + relationship, e.g. "my sister", "my manager Sarah" → `user/people.md`
-- Workplace specifics — company, team, tech stack, tools — "I use Postgres at work" → `user/work.md`
-- Expertise or tools they use habitually — "I've been writing Go for ten years", "I'm new to React" → `user/expertise.md` (add a one-line summary in `profile.md ## Expertise` when the fact also shapes how the agent should explain things)
-- Hobbies, habits, health, lifestyle (factual) — "I run every morning", "I don't eat meat" → `user/personal.md`
-- Goals or learning targets — "I want to get better at Rust", "I want to read 20 books this year" → `user/goals.md`
+- People they know — names + relationship, e.g. "my sister", "my manager Sarah" → `identity/people.md`
+- Workplace specifics — company, team, tech stack, tools — "I use Postgres at work" → `identity/work.md`
+- Expertise or tools they use habitually — "I've been writing Go for ten years", "I'm new to React" → `identity/expertise.md` (add a one-line summary in `profile.md ## Expertise` when the fact also shapes how the agent should explain things)
+- Hobbies, habits, health, lifestyle (factual) — "I run every morning", "I don't eat meat" → `identity/personal.md`
+- Goals or learning targets — "I want to get better at Rust", "I want to read 20 books this year" → `identity/goals.md`
 - A notification or day-type preference — "no work notifications on weekends" → `profile.md ## Notification Preferences`
 - A self-reported behavioral pattern the agent should adapt to — "I'm not a morning person", "I tend to skim long messages" → `profile.md ## Learned Context` with today's `[YYYY-MM-DD]` prefix
 
@@ -40,9 +35,9 @@ Detailed, dictionary-like background belongs under `user/*.md`. Read `user/_inde
 **Routing edge cases** (for shapes the trigger list above doesn't disambiguate):
 - "my name is Alex" — explicit identity statement goes to `profile.md ## Identity`, not a topic file.
 - "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" → `user/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.
+- "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.
 
-See the `message.received.dm.md` / `message.received.dm_first.md` **Capture user info** block for the full decision rule (profile.md vs `user/<topic>.md` tie-breakers, `section_not_found` → `append_to_file` first-write fallback, and a worked `curl` example).
+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.
 
 ## Section ownership
 
@@ -74,6 +69,21 @@ All `user/*.md` files must keep YAML frontmatter with `type: user`,
 section-level PATCH, preserve the existing frontmatter. When doing a
 full-file PUT, update `updated` to today's date.
 
+**Bullet key convention — load-bearing.** Bullets under each H2 use
+**English label keys**, any-language values:
+
+```
+- Name: Alex
+- Timezone: America/New_York
+- Working hours: Weekdays 09:00–18:00
+```
+
+The `user-interview` skill's queue (`state/profile-questions.md`)
+matches against these English keys. If you introduce a non-English
+label here, the queue's slot-filled probe silently misses the bullet
+and re-asks the same question on the next opportunity. See
+`user-interview/SKILL.md` §"Anchor convention — load-bearing".
+
 ## Notification Preferences format
 
 Morning Routine reads this daily to derive today.md's day-type filter. Keep bullets machine-parseable:
@@ -92,31 +102,17 @@ If the user says "I don't want work notifications on weekends", paraphrase into
 
 ## Tone / character preferences
 
-**Tone, style, voice, formality, emoji, verbosity, language preferences 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 `user/profile.md`.
-
-Triggers: "always reply in English", "shorter please", "no emojis", "speak casually", "be more concise", "more formal please", "end every reply with a period".
-
-**Read-before-write still applies.** Do this in one turn:
-
-```bash
-# 1. Read current character
-curl -s http://localhost:8321/api/config/character | jq -r .character
-
-# 2. Merge the new preference into the existing value, then PATCH:
-curl -s -X PATCH http://localhost:8321/api/config/character \
-  -H 'Content-Type: application/json' \
-  -d '{"character": "Speak casually. Tight bullets. No emojis. End every reply with a period."}'
-```
-
-**Endpoint note.** Use `/api/config/character` (narrow, agent-callable),
-not `/api/config` — the general config surface is dashboard-only (Approve
-tier) and will return 401 from an agent curl. The narrow endpoint accepts
-only the `character` field, runs the same Zod validation, and fans the
-new value out to active sessions identically.
+**Tone, style, voice, formality, emoji, verbosity, language
+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`.
 
-**Observe the 1000-char cap.** If the merged value would exceed 1000 characters, surface the excess to the user ("Your style guide is 1180 characters, over the 1000 limit — shall I trim?") rather than silently truncating. Zod rejects over-cap writes with 400 at the API.
+Full recipe — triggers, merge rules, endpoint note, cap-handling, and
+where the value ends up — is in the character-preferences reference
+below.
 
-The character value is written verbatim into every session's `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` between the safety preamble and the profile body. It applies across Claude, Codex, and Gemini uniformly — no separate injection per backend.
+{{> ref:character-preferences }}
 
 ## Read-before-write — mandatory for PATCH replace
 
@@ -126,7 +122,7 @@ See _safety.md "Common Patterns" for the general rule. Section name in PATCH is
 
 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:
 ```bash
-curl -s -X PATCH http://localhost:8321/api/context/user/profile \
+curl -s -X PATCH http://localhost:8321/api/context/identity/profile \
   -H 'Content-Type: application/json' \
   -d '{"section": "learned_context", "mode": "append", "content": "- [2026-04-23] Reading goal: 20 books/year"}'
 ```
@@ -134,7 +130,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), see the **Capture user info** block in `message.received.dm.md` / `message.received.dm_first.md` for the decision rule, the `section_not_found` → `append_to_file` first-write fallback, and a worked `curl` example against `user/people.md`. The read-before-write rule above applies identically when merging into an existing `user/<topic>.md` section.
+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.
 
 ## Learned Context entry format
 
@@ -159,50 +155,34 @@ Review can prune entries older than 30 days:
 
 ## Initial Setup
 
-Populate `user/profile.md` (Identity, Work Pattern, Platforms, Expertise summary, Notification Preferences — leave Learned Context/Raw Signals empty). Read skeleton first → prefer `mode: "append"` → `mode: "replace"` only for full merged body. Tone / style preferences do NOT go into profile.md — see §"Tone / character preferences".
+Populate `identity/profile.md` (Identity, Work Pattern, Platforms, Expertise summary, Notification Preferences — leave Learned Context/Raw Signals empty). Read skeleton first → prefer `mode: "append"` → `mode: "replace"` only for full merged body. Tone / style preferences do NOT go into profile.md — see §"Tone / character preferences".
 
-*During setup, seed `user/profile.md` only. The topic files (`user/people.md`, `work.md`, `expertise.md`, `personal.md`, `goals.md`) stay empty and grow from lived conversation via the DM handler and `routine.user_profile_sweep`.*
+*During setup, seed `identity/profile.md` only. The topic files (`identity/people.md`, `work.md`, `expertise.md`, `personal.md`, `goals.md`) stay empty and grow from lived conversation via the DM handler and `routine.user_profile_sweep`.*
 
 ---
 
 ## API Reference
 
-### Read
-```bash
-curl -s http://localhost:8321/api/context/user/profile              # Full profile
-curl -s http://localhost:8321/api/context/user/_index               # Topic index
-curl -s http://localhost:8321/api/context/user/people               # Specific topic
-```
+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` /
+`work` / `expertise` / `personal` / `goals`).
 
-### PATCH /api/context/user/profile — Section-level edit
-```bash
-curl -s -X PATCH http://localhost:8321/api/context/user/profile \
-  -H 'Content-Type: application/json' \
-  -d '{"section": "learned_context", "mode": "append", "content": "- [YYYY-MM-DD] ..."}'
-```
+Two user-profile-specific notes layered on top of the generic surface:
 
-| Field | Type | Description |
-|---|---|---|
-| `section` | string | snake_case of heading (e.g. `learned_context`) |
-| `mode` | `append` \| `replace` \| `clear` \| `clear_before` | Default `append` |
-| `content` | string | Ignored for `clear` / `clear_before` |
-| `cutoff` | string | `clear_before` only: entries with `[timestamp] ≤ cutoff` are removed (race-safe consumption for Raw Signals) |
-| `maxEntries` | number | `append` only: trims oldest entries to cap (SignalDetector uses cap=20) |
+- **`clear_before` on `## Raw Signals`** is the race-safe consumption
+  path Evening Review uses to drain Raw Signals without dropping
+  concurrent appends. Pass a SQLite-format `cutoff`:
 
-`clear_before` example (Evening Review consuming Raw Signals without dropping concurrent appends):
-```bash
-curl -s -X PATCH http://localhost:8321/api/context/user/profile \
-  -H 'Content-Type: application/json' \
-  -d '{"section": "raw_signals", "mode": "clear_before", "cutoff": "2026-04-10 02:33:00"}'
-```
+  ```bash
+  curl -s -X PATCH http://localhost:8321/api/context/identity/profile \
+    -H 'Content-Type: application/json' \
+    -d '{"section": "raw_signals", "mode": "clear_before", "cutoff": "2026-04-10 02:33:00"}'
+  ```
 
-### PATCH /api/context/user/:topic
-Same shape. Target a section within a topic file:
-```bash
-curl -s -X PATCH http://localhost:8321/api/context/user/people \
-  -H 'Content-Type: application/json' \
-  -d '{"section": "colleagues", "mode": "append", "content": "- Alice: PM on Project X"}'
-```
+- **`maxEntries`** on `## Raw Signals` append is the SignalDetector's
+  cap (= 20). Other writers do not set it.
 
 ## Knowledge map — topic files (auto-curated)
 

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

@@ -7,7 +7,7 @@
       "anchor": "<!-- CURATION:knowledge_layout id=\"topic-files\" -->",
       "human_label": "Topic file layout",
       "description": "Which user/* file owns which kind of fact",
-      "scope_paths": ["user/profile.md", "user/*.md"]
+      "scope_paths": ["identity/profile.md", "user/*.md"]
     },
     {
       "id": "routing-table",
@@ -23,7 +23,7 @@
       "anchor": "<!-- CURATION:convention_notes id=\"learned-context-format\" -->",
       "human_label": "Learned Context bullet conventions",
       "description": "Date-prefix rule, prune cadence, refresh-on-merge",
-      "scope_paths": ["user/profile.md"]
+      "scope_paths": ["identity/profile.md"]
     }
   ]
 }

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

@@ -0,0 +1,83 @@
+---
+kind: reference
+name: character-preferences
+description: Tone / style / voice / language preferences are agent directives — route to PATCH /api/config/character (read-before-write, 1000-char cap, narrow endpoint).
+---
+
+# Tone / character preferences
+
+**Tone, style, voice, formality, emoji, verbosity, language preferences
+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`.
+
+## Triggers
+
+The user is asking for a character change when they say things like:
+
+- "always reply in English" / "speak Japanese from now on"
+- "shorter please" / "be more concise" / "stop padding"
+- "no emojis" / "drop the emojis"
+- "speak casually" / "be more formal please"
+- "end every reply with a period"
+- "don't ask follow-up questions, just answer"
+- "stop with the disclaimers"
+
+If the phrasing reads as a behavioral preference for *how* the agent
+speaks rather than a fact about the user, it belongs in
+`character`, not in profile.md.
+
+## Read-before-write — mandatory
+
+`PATCH /api/config/character` replaces the value wholesale. If you write
+just the new preference, you lose every preference the user previously
+set. Do this in one turn:
+
+```bash
+# 1. Read current character
+curl -s http://localhost:8321/api/config/character | jq -r .character
+
+# 2. Merge the new preference into the existing value, then PATCH:
+curl -s -X PATCH http://localhost:8321/api/config/character \
+  -H 'Content-Type: application/json' \
+  -d '{"character": "Speak casually. Tight bullets. No emojis. End every reply with a period."}'
+```
+
+Merge rules: if the new preference conflicts with an existing one
+(e.g. user used to ask for "formal" and now asks for "casual"), drop
+the old one. If it is additive (a new "no emojis" on top of an
+existing "tight bullets"), append.
+
+## Endpoint note — use the narrow path
+
+Use `/api/config/character` (narrow, agent-callable), **not** `/api/config`.
+The general config surface is dashboard-only (Approve tier) and will
+return 401 from an agent curl. The narrow endpoint accepts only the
+`character` field, runs the same Zod validation, and fans the new value
+out to active sessions identically.
+
+## 1000-char cap
+
+If the merged value would exceed 1000 characters, **surface the excess
+to the user** ("Your style guide is 1180 characters, over the 1000
+limit — shall I trim?") rather than silently truncating. Zod rejects
+over-cap writes with HTTP 400 at the API.
+
+A character value over the cap usually means the user added a
+preference that *replaces* an older one rather than extending it —
+offer to drop the obsoleted bullet as the first trim candidate.
+
+## Where the value ends up
+
+The character value is written verbatim into every session's
+`CLAUDE.md` / `AGENTS.md` / `GEMINI.md` between the safety preamble
+and the profile body. It applies across Claude, Codex, and Gemini
+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
+`character`. The split is: `character` says *how* the agent speaks;
+`user/*` says *who the user is*.