@aitne-sh/aitne 0.1.0

package/agent-assets/task-flows/git.project.refresh_architecture.md

@@ -0,0 +1,100 @@
+{context}
+
+# Task Flow: Refresh Repository Architecture Section
+
+You are producing the body of the `## Architecture` section in
+`git/<slug>/overview.md` for a registered repository. The dashboard's
+"Refresh architecture" button (or the auto-enqueue at manual init time)
+created this `git.project.refresh_architecture` task. The daemon owns the
+surgical merge — you submit only the new section body and it replaces the
+marker-bracketed Architecture block in place. Other sections (Summary,
+Notable Changes, Daily Activity Log) are preserved automatically.
+
+## Inputs
+
+Read `<task_context>` first. It contains:
+
+- `repositoryId` — opaque ID; pass it back on the write call below.
+- `slug` — the directory slug under `git/`; the overview is at `git/<slug>/overview.md`.
+- `localPath` — absolute path to the repository's local clone. **Read directly from this path** with the Read tool; you do NOT need to `cd` into it.
+- `githubRepo` — `owner/repo` string when GitHub-linked, otherwise `null`.
+- `classification` — `"project"` or `"non-project"`.
+- `category` — operator-supplied category label.
+
+## Goal
+
+Produce a thorough, evergreen Architecture analysis suitable for a
+project-overview document. Aim at a reader who is technical but new to
+the repo. Cover, **only as the repo actually warrants**:
+
+- **Top-level layout and module map.** What lives in each top-level dir,
+  what each package owns, what the entry points are.
+- **Runtime shape.** Long-running daemon vs. CLI vs. library. Process
+  lifecycle. Background workers, schedulers, cron, observers, web servers.
+- **Data flow.** How input enters the system, how it's stored
+  (database, files, in-memory), how it leaves (API, write to disk,
+  emitted events).
+- **Persistence.** Database tables/schemas, file conventions, caches,
+  migration approach.
+- **External integrations.** APIs called, services consumed, auth model.
+- **Build / packaging.** Languages, build tooling, monorepo structure
+  if any, how it's installed/distributed.
+- **Test surface.** Test framework, structure, what's covered vs. not.
+- **Notable design choices.** Patterns the codebase commits to (DI,
+  message bus, event sourcing, plugin registries, etc.) and the
+  invariants those patterns enforce.
+
+Skip generic boilerplate. Don't list every file or every script —
+synthesize.
+
+## Steps
+
+1. **Read the README** at `<localPath>/README.md` (or `README.*`). Use
+   it as the author's stated framing of the project, but verify against
+   the code; the README can drift.
+2. **Survey top-level structure.** `ls <localPath>` + targeted reads of
+   `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod` / etc. to
+   identify the language, build system, and entry points.
+3. **Walk the meaningful directories.** Read enough source to confirm
+   each module's responsibility. Prefer reading entry points,
+   manifests, and central registries (e.g. a router, a server bootstrap,
+   a scheduler) over leaf files.
+4. **Cross-check the design docs** if `docs/` or `design/` exists —
+   these often record invariants that aren't visible from code alone.
+   Cite the doc filename when you rely on it.
+5. **Write the Architecture body.** Compose well-structured Markdown:
+   - Use `### ` and `#### ` for sub-sections (NOT `## ` — that boundary
+     belongs to the parent file).
+   - Use bulleted lists, short prose paragraphs, and small tables where
+     they communicate better than prose.
+   - File / dir references use backticks (e.g. `packages/daemon/src/`).
+   - Code references use the `path/to/file.ext:line` form so a reader
+     can jump to the source.
+   - **Do NOT include** the `<!-- architecture:start -->` /
+     `<!-- architecture:end -->` markers in your submission — the daemon
+     wraps your body with them.
+6. **Submit the section.** One write, one shot:
+
+   ```
+   PUT /api/repositories/<repositoryId>/architecture-section
+   { "markdown": "<your section body>" }
+   ```
+
+   Use curl from the session workdir (no Bearer token needed — this
+   endpoint is agent-callable).
+
+## Stopping conditions
+
+- Target ~6–15 turns. If you reach 25 turns, finalize whatever you have
+  and submit it; a partial-but-honest Architecture section beats an
+  unfinished one that never lands.
+- If `localPath` does not exist or is not a git worktree, abort and
+  surface the error in your final response — do NOT submit a placeholder.
+- Do not call any other write endpoint. Your only output is the single
+  `PUT /architecture-section` call.
+
+## Final response
+
+Keep it brief. One sentence confirming the write landed (or summarizing
+why it could not). The dashboard reads the file directly; there is no
+need to DM the owner.

package/agent-assets/task-flows/git.project.retemplate.md

@@ -0,0 +1,73 @@
+{context}
+
+# Task Flow: Git Project Re-Template
+
+You are re-conforming durable Git project context files to a newly edited
+template. The dashboard's "Apply current template" action created the
+`git.project.retemplate` task and pre-backed up every target file before
+this session started, so writes here are reversible by the daemon's
+finalize step on failure.
+
+Use the `project-doc` skill rules for all reads and writes.
+
+## Inputs
+
+Read `<task_context>` first. It contains:
+
+- `kind` — `"project"` or `"git-repo"` (which template family is being applied).
+- `templateName` — `project.md` or `git-repo.md`.
+- `templateContent` — the full body of the current `~/.personal-agent/templates/<templateName>` (verbatim, including frontmatter and section headings).
+- `targets` — array of `{ slug, contextPath, contextFile, classification, category, repoPath, accountAlias, org, backupRelPath }`. Each entry is one file you must process. The list is finite and pre-validated; do not add or skip targets that are not in this array.
+- `backupRoot` — absolute path containing the auto-backup of every target before this session started.
+- `correlationId` — pass this back on every per-file status report (the daemon uses it to attribute audit rows to this run).
+
+## Steps
+
+For each `target` in `targets`, in order:
+
+1. **Mark started.** Before reading or writing anything for this file, report:
+
+   ```
+   POST /api/git/templates/retemplate/file
+   { "slug": "<target.slug>", "status": "started", "correlationId": "<correlationId>" }
+   ```
+
+   The daemon stamps this in the status grid; if the session aborts after this point, the daemon's finalize step will restore the file from `<backupRoot>/<target.backupRelPath>`.
+
+2. **Read the current file.** `GET /api/context/<target.contextPath>`. If the file is missing (404), report `{"status":"skipped","reason":"missing"}` and continue. (The daemon enumerates targets from disk before enqueue, so a 404 here means the user moved or deleted the file in between — accept silently.)
+
+3. **Compare against the template.** Quickly check whether the existing body already conforms to `templateContent` (same set of `## ...` headings in the same order, same frontmatter keys, no extra top-level structure). If yes, report `{"status":"skipped","reason":"already_conformed"}` and continue. Idempotency is essential — re-running the action must be cheap.
+
+4. **Re-shape the body.** Produce a new body that:
+   - Uses `templateContent` as the structural source: every section heading and frontmatter key the template defines must be present in the same order.
+   - **Preserves user information wherever possible.** Manual prose under `## Open Threads`, `## Notable Changes`, `## Lifecycle Phases`, etc., maps onto the same heading in the new template. If the new template drops a heading, fold its content into the most semantically related surviving heading rather than discarding it. Add a one-line `<!-- migrated from: <old heading> -->` HTML comment beside any folded block so a later editor can audit the transformation.
+   - Keeps the existing frontmatter values for `slug`, `git_repo`, `default_branch`, `remote`, `created`, `account_alias`, `category`, `org`, and any other identifiers — only the *shape* of the frontmatter changes, not the data. Set `updated:` to today's ISO date.
+   - For `kind: "project"`: leaves `## Git Activity`, `## Notable Changes`, `## Lifecycle Phases` populated with whatever the existing file said. Do not refetch git history here — the goal is structural conformance, not refresh.
+   - For `kind: "git-repo"`: leaves `## Activity` and `## Recent Pushes` intact.
+
+5. **Write the new body.** `PUT /api/context/<target.contextPath>` with `{ "content": "<full markdown>" }`.
+
+6. **Mark completed.**
+
+   ```
+   POST /api/git/templates/retemplate/file
+   { "slug": "<target.slug>", "status": "completed", "correlationId": "<correlationId>", "beforeBytes": <int>, "afterBytes": <int> }
+   ```
+
+7. **On a per-file error** (`PUT` returns non-2xx, body is malformed, etc.):
+
+   ```
+   POST /api/git/templates/retemplate/file
+   { "slug": "<target.slug>", "status": "failed", "correlationId": "<correlationId>", "error": "<short message>" }
+   ```
+
+   Do **not** attempt to roll back yourself — the daemon's finalize step owns rollback. Continue with the next target.
+
+## Stopping conditions
+
+- Process every target in order, even if some fail. Do not abort the whole run on a single per-file failure.
+- If you encounter the same systemic error on three consecutive targets (e.g. context API returning 503), stop and let the daemon mark the run failed — there is no point burning quota against a broken vault.
+
+## Final response
+
+Keep it silent/internal. The dashboard reads the status grid via `GET /api/git/templates/retemplate/status`; there is no need to DM the owner unless the entire flow could not start (no targets, missing template, etc.) and the user needs to act in the dashboard.

package/agent-assets/task-flows/git.push.detected.md

@@ -0,0 +1,32 @@
+{context}
+
+## Git - Push Detected
+Repository path: {event_data[repoPath]}
+Branch: {event_data[branch]}
+Default branch: {event_data[defaultBranch]}
+Previous remote SHA: {event_data[previousRemoteHash]}
+Remote SHA: {event_data[remoteHash]}
+Force-push check: {event_data[forcePushCheck]}
+
+A watched remote branch moved. This bundled flow is observation-only by
+default; it exists so a future user override has a clear base behavior.
+
+### Decision Framework
+
+1. Do not send a DM. A normal push is expected repository activity and
+   should be coalesced by the hourly observation review.
+2. If this push is on the default branch and materially changes current
+   work, append one concise line to today.md `## Agent Notes`. Keep it
+   factual: repository path, branch, short SHA, and subject if available
+   in the event data.
+3. If the push is noisy or lacks enough context to act on, log one line
+   to `## Agent Log` and stop.
+4. Mark any observation you consume as processed through the observations
+   API.
+
+### Boundaries
+
+- Do not run write operations against the repository.
+- Do not push, pull with merge/rebase, reset, checkout, or create tags.
+- Do not notify the user unless they have replaced this bundled flow with
+  an explicit override.

package/agent-assets/task-flows/git.push.force_pushed.md

@@ -0,0 +1,36 @@
+{context}
+
+## Git - Force Push Detected
+Repository path: {event_data[repoPath]}
+Branch: {event_data[branch]}
+Default branch: {event_data[defaultBranch]}
+Previous remote SHA: {event_data[previousRemoteHash]}
+New remote SHA: {event_data[remoteHash]}
+Force-push check: {event_data[forcePushCheck]}
+
+A watched remote branch was rewritten: the new remote SHA does not contain
+the previous remote SHA in its ancestry. The poller emits this as a
+high-priority event because history rewrites can invalidate local work,
+reviews, CI results, and release assumptions.
+
+### Decision Framework
+
+1. Default: send one high-priority DM. Keep it short and factual:
+   repository path, branch, previous short SHA, new short SHA.
+2. Stay silent only if today.md `## Agent Log` already records a DM for
+   the same repository, branch, previous SHA, and new SHA.
+3. Use `POST /api/notify` with priority `high`. Suggested format:
+   ```
+   Force-push detected on {event_data[repoPath]} ({event_data[branch]}):
+   {event_data[previousRemoteHash]} -> {event_data[remoteHash]}
+   ```
+4. Append a matching audit line to today.md `## Agent Log`:
+   `- HH:MM [git] force-push {event_data[repoPath]} {event_data[branch]} - notified`
+
+### Boundaries
+
+- Do not attempt recovery. The agent must not reset, rebase, merge, push,
+  checkout, or edit repository files.
+- Do not diagnose blame or intent. Report the rewrite and let the user
+  decide the next action.
+- Do not include diff contents in the DM.

package/agent-assets/task-flows/git.tag.created.md

@@ -0,0 +1,24 @@
+{context}
+
+## Git - Tag Created
+Repository path: {event_data[repoPath]}
+Tag: {event_data[tag]}
+Tag SHA: {event_data[tagHash]}
+Default branch: {event_data[defaultBranch]}
+
+A new remote tag appeared in a watched repository.
+
+### Decision Framework
+
+1. Do not send a DM by default. Tags and releases are recorded for
+   hourly review and project documentation updates.
+2. If the tag clearly represents an active release the user is tracking
+   today, append one concise line to today.md `## Agent Notes`.
+3. If it is routine versioning or lacks current-day relevance, log one
+   line to `## Agent Log` and consume the observation.
+
+### Boundaries
+
+- Do not create, delete, move, or push tags.
+- Do not call release APIs that mutate GitHub/GitLab state.
+- Do not notify the user unless a user override explicitly asks for it.

package/agent-assets/task-flows/github.assigned.md

@@ -0,0 +1,43 @@
+{context}
+
+## GitHub — Assigned
+Repository: {event_data[repository]}
+Subject: {event_data[subjectTitle]}
+Type: {event_data[subjectType]}
+URL: {event_data[subjectUrl]}
+Updated: {event_data[updatedAt]}
+Notification ID: {event_data[notificationId]}
+
+You have been assigned to this issue or PR. The poller already recorded
+an observation; this session decides whether to DM the user now.
+
+### Decision Framework
+
+The notify skill's awareness gate applies. The user can see the same
+notification in their GitHub inbox. A DM is warranted only when the
+agent's context says the assignment is **urgent** or **conflicts with
+in-flight work**.
+
+1. **Default: DM at `high` priority.** GitHub assignment is an explicit
+   request for the user's attention from a human. The default is to
+   surface it within the hour, not wait for the hourly check.
+
+2. **Stay silent only when**:
+   - `today.md` `## Agent Plan` already references this assignment.
+   - The same subject was assigned-then-unassigned within the past
+     30 minutes (check via observations: same `notificationId` payload
+     across `consumed` rows).
+
+3. **Send via `POST /api/notify`** at priority `high`. Suggested format:
+   ```
+   Assigned on {event_data[repository]}: {event_data[subjectTitle]}
+   {event_data[subjectUrl]}
+   ```
+
+4. **Always log** to `## Agent Log`:
+   `- HH:MM [github] assigned {event_data[repository]} {event_data[subjectType]} — <outcome>`
+
+### Boundaries
+
+- Do NOT auto-accept, label, or comment on the issue/PR. Assignment
+  notifications are read-only signals.

package/agent-assets/task-flows/github.pull_request.review_requested.md

@@ -0,0 +1,57 @@
+{context}
+
+## GitHub — Review Requested
+Repository: {event_data[repository]}
+Pull Request: {event_data[subjectTitle]}
+URL: {event_data[subjectUrl]}
+Updated: {event_data[updatedAt]}
+Notification ID: {event_data[notificationId]}
+
+A teammate (or bot) has requested your review on this PR. The poller has
+already recorded an observation; this session decides whether to DM the
+user now or stay silent and let the hourly check coalesce it later.
+
+### Decision Framework
+
+The notify skill's awareness gate applies — the user can see the same
+notification in their GitHub inbox or email. A DM is warranted only when
+the agent's context says the request is **time-sensitive** or **at risk
+of being missed**.
+
+1. **Default: do NOT DM.** Append a heads-up to today.md
+   `## Agent Notes` per the context skill, citing the repository, PR
+   title, and URL. The hourly check will surface the request in its next
+   coalesced summary if still open.
+
+2. **DM at `high` priority** if any of the following hold:
+   - The PR title contains a release-blocker keyword (`hotfix`,
+     `revert`, `urgent`, `security`).
+   - `today.md` has a `## Agent Plan` entry that mentions this
+     repository or PR number — the user is already context-loaded on it.
+   - The roadmap has an active milestone tied to this repository.
+
+   For the third trigger, fetch context once:
+
+   ```bash
+   curl -s http://localhost:8321/api/context/roadmap | grep -i "{event_data[repository]}"
+   ```
+
+   If non-empty, the milestone tie is real.
+
+3. **Send via `POST /api/notify`** at priority `high`. Include the PR
+   title, repository, and URL. Keep it under 200 characters — the user
+   can click through for the full diff. Never include the entire diff
+   inline.
+
+4. **Always log the decision** to `## Agent Log` per the context skill,
+   even when staying silent. Format:
+   `- HH:MM [github] review requested {event_data[repository]} #<num> — <outcome>`
+   where outcome is `notified` or `silent (awareness gate)`.
+
+### Boundaries
+
+- The agent does NOT post a review comment on the PR. Reviews are the
+  user's call.
+- If the PR is already merged or closed by the time you check (rare —
+  the notification fired moments ago), log `stale (PR closed)` and
+  exit silently.

package/agent-assets/task-flows/github.security_alert.md

@@ -0,0 +1,45 @@
+{context}
+
+## GitHub — Security Alert
+Repository: {event_data[repository]}
+Subject: {event_data[subjectTitle]}
+Type: {event_data[subjectType]}
+URL: {event_data[subjectUrl]}
+Updated: {event_data[updatedAt]}
+Notification ID: {event_data[notificationId]}
+
+A Dependabot or code-scanning security alert has fired on a watched
+repository. This is a `high`-priority event by default — security
+issues warrant prompt awareness even when the user is mid-task.
+
+### Decision Framework
+
+1. **Default: DM at `high` priority.** Security alerts surface
+   vulnerabilities the user is unlikely to discover on their own. Do not
+   wait for the hourly check.
+
+2. **Stay silent only when** the same alert already triggered a DM
+   within the past 24 hours (check by `notificationId` in observations
+   payload). Repeated identical pings are noise.
+
+3. **Send via `POST /api/notify`** at priority `high`. Suggested format:
+   ```
+   Security alert on {event_data[repository]}:
+   {event_data[subjectTitle]}
+   {event_data[subjectUrl]}
+   ```
+
+   Do NOT include CVE numbers or affected-package details inline — the
+   URL provides the full context, and quoting partial CVE info risks
+   misrepresenting severity.
+
+4. **Always log** to `## Agent Log`:
+   `- HH:MM [github] security_alert {event_data[repository]} — <outcome>`
+
+### Boundaries
+
+- Do NOT attempt to update dependencies, accept Dependabot PRs, or
+  modify security policies. The agent's role here is purely to surface
+  the alert.
+- Do NOT cross-reference unrelated repositories' security alerts in
+  the same DM. Stick to the subject of this notification.

package/agent-assets/task-flows/github.workflow_run.failed.md

@@ -0,0 +1,57 @@
+{context}
+
+## GitHub — Workflow Run Failed
+Repository: {event_data[repository]}
+Workflow: {event_data[workflowName]}
+Title: {event_data[displayTitle]}
+Branch: {event_data[branch]}  (default: {event_data[defaultBranch]})
+On default branch: {event_data[onDefaultBranch]}
+Conclusion: {event_data[conclusion]}
+URL: {event_data[htmlUrl]}
+Run ID: {event_data[runId]}
+Trigger event: {event_data[triggerEvent]}
+
+A workflow has failed. This task-flow only fires for failures on the
+default branch (the poller filters feature-branch failures to
+observation-only). The user almost always wants to know about a default-
+branch failure, but the awareness gate still matters — they may have
+just pushed and be watching the runs page.
+
+### Decision Framework
+
+1. **Default: DM at `high` priority.** Default-branch CI failures block
+   downstream work — releases, dependent PRs, deploys. Send a short DM
+   with the workflow name, branch, and URL. Do NOT include the failing
+   step's log output inline; the URL is sufficient.
+
+2. **Stay silent only when** one of the following clearly holds:
+   - `today.md` `## Agent Plan` already has an entry referring to this
+     workflow run by name (the user is already triaging it).
+   - The same workflow has produced a `failed` observation within the
+     past 30 minutes that already triggered a DM (check via
+     `GET /api/observations?source=github:workflow:{event_data[repository]}&pending=false&limit=10`
+     and inspect timestamps + payloads). De-dup keeps the user's signal
+     channel clean during a flaky CI cascade.
+   - The trigger event is `schedule` (cron-driven) AND the user has a
+     known pattern of cron failures they don't want paged on. This is
+     opt-out territory — only stay silent if `roadmap.md` or
+     `user.md` explicitly says so.
+
+3. **Send via `POST /api/notify`** at priority `high`. Suggested format:
+   ```
+   CI failed on {event_data[repository]} ({event_data[branch]}):
+   {event_data[workflowName]} — {event_data[htmlUrl]}
+   ```
+
+4. **Always log the decision** to `## Agent Log` even if silent.
+   Format:
+   `- HH:MM [github] workflow_run failed {event_data[repository]} {event_data[workflowName]} — <outcome>`
+
+### Boundaries
+
+- Do NOT attempt to re-run the workflow. The agent has no `gh run rerun`
+  permission, and the safety policy is read-only for git/GitHub.
+- Do NOT fetch the failing job's log content unless the user explicitly
+  asks in a follow-up DM — the URL is enough for the first ping.
+- Do NOT cross-reference unrelated PRs or issues. Stick to the failed
+  run's repository.

package/agent-assets/task-flows/knowledge.import.md

@@ -0,0 +1,161 @@
+{context}
+
+## Task: Knowledge Import — write user-supplied facts into `user/*.md`
+
+The user has uploaded a single Markdown or text file from the dashboard Knowledge page. Your job is to read it and route its facts into the appropriate `user/*.md` files **without changing what the user wrote**. The CLAUDE.md / AGENTS.md / GEMINI.md materialized for this session contains your full Profile Importer persona — re-read it before writing if you're unsure.
+
+The event payload (substituted into this prompt) carries:
+- `{event_data[scratchPath]}` — context-relative path of the scratch copy of the upload (e.g. `agent/scratch/import-2026-04-27-<id>.md`)
+- `{event_data[filename]}` — the original filename
+- `{event_data[importSource]}` — origin label the user picked (`obsidian-export`, `notion-export`, `self-written`, `other`). Note: `event_data[source]` is the daemon-side event source (e.g. `"dashboard_knowledge_upload"`), not what the user selected — use `importSource`.
+- `{event_data[uploadDate]}` — ISO date string for the closing journal entry
+
+### Step 1 — Read the upload (verbatim)
+
+```
+curl -s "http://localhost:8321/api/context/{event_data[scratchPath]}"
+```
+
+The response is JSON; the `content` field is the literal source text. Every fact you write to `user/*.md` must be traceable to a line in this file.
+
+### Step 2 — Hard stop on secret-shaped content
+
+If the source contains any of:
+- `-----BEGIN ... PRIVATE KEY-----`
+- AWS keys (`AKIA[0-9A-Z]{16}`), Google API keys (`AIza[0-9A-Za-z_-]{35}`), GitHub tokens (`gh[pousr]_[A-Za-z0-9]{36,}`), or Slack tokens (`xox[abp]-`)
+- Lines that look like `password:` / `secret:` / `token:` followed by a non-empty value
+
+ABORT the import. Do not write anything to `user/*.md`. Notify the owner via `/api/notify` (the `notify` skill is loaded for this exact purpose):
+
+```
+curl -s -X POST http://localhost:8321/api/notify \
+  -H 'Content-Type: application/json' \
+  -d '{"message": "Knowledge import refused — the upload contained content shaped like a private key, API token, or credential. No files were modified. Please remove the sensitive content and re-upload.", "priority": "normal"}'
+```
+
+Then append this entry to `agent/journal.md` using `mode: "append_to_file"` (each journal entry is its own top-level `## ` section):
+
+```
+curl -s -X PATCH http://localhost:8321/api/context/agent/journal \
+  -H 'Content-Type: application/json' \
+  -d "$(jq -nc --arg c '
+## {event_data[uploadDate]} knowledge import REFUSED (source={event_data[importSource]}, file={event_data[filename]})
+- Reason: secret-shaped content at line N
+- No files modified.' '{mode:"append_to_file", content:$c}')"
+```
+
+Then end the session.
+
+### Step 3 — Discover the knowledge layout
+
+```
+curl -s "http://localhost:8321/api/context/list/user"
+```
+
+The response shape is `{"files": [{"name": "profile.md", "lastModified": "..."}, ...]}`. Build a Set of existing topic file basenames (`profile`, `people`, `work`, `expertise`, `personal`, `goals`, plus any others present). Treat this Set as authoritative — only read or PATCH files in this Set.
+
+If the listing is empty (no `user/*.md` files exist at all), the user has not completed initial setup. ABORT with a journal entry "skeleton not seeded — initial setup incomplete" and end the session. (The route layer also gates this, so this is a defense-in-depth check.)
+
+### Step 4 — Read each existing target file once
+
+For every basename in the Set from Step 3, fetch the body:
+
+```
+curl -s "http://localhost:8321/api/context/user/<basename>"
+```
+
+You need the current body to:
+1. Skip facts that are already present (substring or near-substring match — be conservative; skip on doubt).
+2. Detect conflicts (existing bullet contradicts source bullet — see Step 6).
+3. Discover the file's existing `## Section` headings (you'll need these for PATCH `section` parameters in Step 6).
+4. Preserve the file's frontmatter and section structure.
+
+### Step 5 — Classify each source fact and route
+
+Standard routing (see also `user-profile` skill):
+
+| Class | Target |
+|---|---|
+| Identity (legal name, primary timezone, primary language, DOB) | **DO NOT WRITE.** Collect verbatim for the Step 8 journal entry under "Identity-class facts awaiting confirmation". The dashboard surfaces these for explicit accept/reject — they never auto-land in `user/profile.md`. |
+| Relationships (family, partners, close friends) | `user/people.md` |
+| Work / employer / role / colleagues | `user/work.md` |
+| Skills, expertise, languages spoken | `user/expertise.md` |
+| Lifestyle, hobbies, preferences, health | `user/personal.md` |
+| Goals, aspirations, current focus | `user/goals.md` |
+
+Routing rules:
+- If the natural target file is **missing from the Step 3 Set**, route the fact to `user/profile.md` instead and prefix its bullet with `[from <missing-file>]` (e.g. `- [from work.md] Works at Acme.`) so the user can later move it. Skip the route only if `user/profile.md` itself is also missing — in that case Step 3's empty-listing abort already fired.
+- If a fact does not fit any class, append it to `user/profile.md` in a section named `## Misc` (verbatim — no parens, no date in the heading, because `normalizeSection` does not preserve them). Date the bullet inline: `- [imported {event_data[uploadDate]}] <verbatim line>`.
+
+### Step 6 — Apply writes (verbatim, append-only) via section PATCH
+
+`PATCH /api/context/<path>` operates on a single `## Section`, NOT on the full file body. The schema is:
+
+```
+{
+  "section": "<snake_case_of_heading>",                          # e.g. "## Family" → "family", "## Roles" → "roles"
+  "mode":    "append" | "replace" | "clear" | "append_to_file",  # use "append" for facts; never "replace" here
+  "content": "- <verbatim bullet>"                               # multiple bullets joined with \n
+}
+```
+
+For each target file with at least one new fact:
+
+1. `curl -s "http://localhost:8321/api/context/user/<topic>"` once. From the body, list every existing `## ` heading and the bullets they contain. You'll use this to (a) skip duplicates, (b) pick a section name, (c) detect conflicts.
+
+2. Group new facts by destination section. Each bullet must be a **verbatim** copy of a line from the source — strip only leading list markers (`- `, `* `, `1. `) and surrounding whitespace. Skip any line whose substance is already present in the target section.
+
+3. For each (section, bullets) group, PATCH with `mode: "append"`. Multiple bullets go in ONE call, joined by `\n`:
+
+```
+curl -s -X PATCH http://localhost:8321/api/context/user/<topic> \
+  -H 'Content-Type: application/json' \
+  -d "$(jq -nc --arg s 'family' \
+                --arg c '- Sister (Sarah): two kids as of 2026-04
+- 母 Yoko (1955–)' \
+              '{section:$s, mode:"append", content:$c}')"
+```
+
+4. **`section_not_found` fallback.** If the response is `{"error": "section_not_found"}`, the section does not exist yet. Retry with `mode: "append_to_file"` and put the heading into the content (with a leading newline so it lands on its own line):
+
+```
+curl -s -X PATCH http://localhost:8321/api/context/user/<topic> \
+  -H 'Content-Type: application/json' \
+  -d '{"mode": "append_to_file", "content": "\n## Family\n- Sister (Sarah): two kids as of 2026-04"}'
+```
+
+The next PATCH to `section: "family"` on the same file then succeeds normally.
+
+5. **Conflict handling.** If a source bullet contradicts an existing bullet in some section, DO NOT touch the original section. Instead, append the source bullet to a separate `## Pending Conflicts` section on the same file, with each bullet prefixed `- [imported {event_data[uploadDate]}] ` so the date stays inline. First write to that section uses the `append_to_file` fallback (with content `\n## Pending Conflicts\n- [imported {event_data[uploadDate]}] <bullet>`); subsequent writes use `mode: "append"` with `section: "pending_conflicts"`. Note each conflict in the closing journal entry.
+
+6. **Never use `mode: "replace"` in this flow.** Replace overwrites the entire section body and would erase facts that aren't in the import. Append-only is the strict-fidelity guarantee.
+
+7. **404 handling.** If a GET or PATCH responds with `{"error": "not_found"}` (the file vanished between Step 3 and Step 6), drop that file from the run, count its facts under "Skipped — file_not_found" in the closing journal entry, and continue with the remaining files. Do not retry, do not create the file with PUT — file creation is the setup wizard's job, not this session's.
+
+### Step 7 — Identity-class deferral
+
+This is a no-write step. From the source, collect every Identity-class fact (legal name, primary timezone, primary language, date of birth, primary email, primary phone) into a list, **verbatim**. Do NOT PATCH them anywhere. The Step 8 journal entry surfaces them under "Identity-class facts awaiting confirmation"; the dashboard reads that section to offer the user an explicit accept/reject decision later. Identity-class fields are too high-stakes to land in `user/profile.md` from an import.
+
+### Step 8 — Closing journal entry
+
+After all PATCHes succeed, append exactly one entry to `agent/journal.md`. Each journal entry is its own top-level `## ` section, so use `mode: "append_to_file"` and embed the heading in the content (leading `\n` so it lands on its own line):
+
+```
+curl -s -X PATCH http://localhost:8321/api/context/agent/journal \
+  -H 'Content-Type: application/json' \
+  -d "$(jq -nc --arg c '
+## {event_data[uploadDate]} knowledge import (source={event_data[importSource]}, file={event_data[filename]})
+- Wrote <N> facts to <comma-separated file paths>
+- Skipped <M> lines — reasons: <ambiguous=A, already-present=B, identity-class-deferred=C>
+- Pending conflicts: <list of file:section pairs, or "none">
+- Identity-class facts awaiting confirmation: <verbatim list, or "none">' '{mode:"append_to_file", content:$c}')"
+```
+
+Then end the session. No DM (other than the Step 2 abort notification when applicable), no follow-up schedule, no other writes.
+
+### Reminders
+
+- The persona file (CLAUDE.md / AGENTS.md / GEMINI.md depending on this session's backend) is the source of truth for fidelity rules. Re-read its "non-negotiable rule" section if you find yourself wanting to "polish" a bullet.
+- Read the target file once before writing — needed to dedupe, to pick the right section name, and to detect conflicts. PATCH itself is section-targeted and does not require `expectedMtime` (that is the PUT contract; ignore it here).
+- Group bullets by section: one PATCH per (file, section), with multiple bullets joined by `\n` in `content`. Do not send one PATCH per bullet.
+- `mode: "append"` only. Never `mode: "replace"` on existing sections — that would erase the user's prior facts.