npm - @aitne-sh/aitne - Versions diffs - 0.1.0 - Mend

@aitne-sh/aitne 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (249) hide show

package/agent-assets/skills/notion/SKILL.delegated.gemini.md ADDED Viewed

@@ -0,0 +1,194 @@
+---
+name: notion
+description: Load when the task touches Notion and Notion is in cross-backend delegated mode (DM session is Gemini CLI; `delegatedBackend` is non-Gemini). All Notion operations flow through `POST /api/integrations/notion/exec`; `/api/notion/*` write/read endpoints are not active in this configuration. The label-resolution endpoint `GET /api/notion/databases` remains available.
+---
+# Notion (delegated, cross-backend)
+Your DM session runs on Gemini CLI. Notion access has been delegated
+to a *different* backend (Claude or Codex) whose Notion connector is
+signed in. **You describe Notion intent in natural language; the
+daemon picks the tool.** Tool name divergence between Claude
+(`notion-search`, `notion-create-pages`), Codex (`search`,
+`notion_create_pages`) and any custom Notion MCP server is invisible
+to you.
+To check which backend currently owns Notion, read
+`~/.personal-agent/integrations.md`. The `/exec` body below is
+backend-agnostic.
+## 1. Label resolution (still direct)
+Database UUIDs are unstable; the user's labels (e.g. `"projects"`,
+`"meeting-notes"`) map to UUIDs through the daemon's settings store.
+This route is NOT proxied — it returns the configured map even in
+delegated mode:
+```bash
+curl -sS http://localhost:8321/api/notion/databases
+# → { databases: { "<label>": { "id": "<uuid>", "title": "..." }, ... } }
+```
+Resolve label → UUID here BEFORE the `/exec` call so your `task`
+prose carries a concrete data-source URL or UUID.
+## 2. The single call shape
+```bash
+curl -sS -X POST http://localhost:8321/api/integrations/notion/exec \
+  -H 'Content-Type: application/json' \
+  -d '{"task": "<natural-language intent>", "outputSchema": { ... }, "cacheable": true}'
+```
+The daemon:
+1. Verifies Notion is in `mode="delegated"`. If not, you get
+   `409 mode_mismatch` — re-read `integrations.md` and stop.
+2. Spawns the delegatedBackend in a tempdir, lets it pick the right
+   tool against the per-task allowed-tools envelope, validates the
+   final JSON against your `outputSchema`, returns it.
+`outputSchema` is **required** (4 KB cap). Defaults: `maxToolCalls=7`,
+`maxBudgetUsd=0.05`, `timeoutMs=60000`. Bump up to 15 / 0.50 / 300000
+for genuinely larger intents.
+## 3. Worked examples
+### Search + structured listing (read)
+```bash
+curl -sS -X POST http://localhost:8321/api/integrations/notion/exec \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "task": "List the top-level pages in the Tasks database (data source <UUID>). For each page return the title, status (if a Status property exists), and last-edited timestamp. Sort by last-edited descending.",
+    "outputSchema": {
+      "type": "object",
+      "required": ["pages"],
+      "properties": {
+        "pages": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "title", "lastEditedAt"],
+            "properties": {
+              "id":           {"type": "string"},
+              "title":        {"type": "string"},
+              "status":       {"type": "string"},
+              "lastEditedAt": {"type": "string", "format": "date-time"}
+            }
+          }
+        }
+      }
+    },
+    "maxToolCalls": 5,
+    "cacheable": true
+  }'
+```
+### Create a page (destructive — confirmation required)
+```bash
+curl -sS -X POST http://localhost:8321/api/integrations/notion/exec \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "task": "Create a new page under the Projects database (data source <UUID>) titled \"Migration plan — May\". Body: <BODY>. Properties: Status=\"Active\", Owner=<USER_ID>.",
+    "outputSchema": {
+      "type": "object",
+      "required": ["pageId", "url"],
+      "properties": {
+        "pageId": {"type": "string"},
+        "url":    {"type": "string"}
+      }
+    },
+    "allowDestructive": true
+  }'
+```
+## 4. Destructive-confirm two-step (`allowDestructive`)
+Default is `false`. The subprocess will not run create / update /
+delete / move / duplicate / comment — instead it returns:
+```jsonc
+{
+  "needsConfirmation": true,
+  "confirmationPlan": "I will create a new page titled \"Migration plan — May\" under the Projects database with status \"Active\"."
+}
+```
+Surface the plan to the user verbatim. On their explicit OK, re-issue
+the **same `task` verbatim** with `allowDestructive: true`. Never set
+`cacheable: true` on the second call.
+## 5. `cacheable: true` for read-only Notion lookups
+60s TTL — well-suited to follow-up reads on the same page tree. Skip
+caching when the user explicitly asked about a recent edit, and never
+on writes or the destructive-confirm second call.
+## 6. Decision rules
+### Page archive — workaround only
+Neither hosted connector exposes a page-archive tool. Phrase the
+intent as one of:
+1. **Property workaround**: "Set Status = Archived on page <UUID>."
+2. **Move to a Trash page**: "Move page <UUID> under the top-level
+   Trash page (creating Trash if it doesn't exist)."
+### Schema admin — Approve-tier intent
+Database / view / data-source mutations change workspace structure.
+Surface what you'd do before invoking, and ask the user.
+### Mass-update — ask first
+If the intent would touch more than ~10 pages, summarize the plan and
+ask before executing.
+### Structured database filtering
+Phrase property-equality intents as the WHERE clause; the subprocess
+picks the right primitive whichever connector is active.
+## 7. Error envelope
+| HTTP | `error` | retry? | What to do |
+|---|---|---|---|
+| 400 | `validation_error` / `schema_too_large` | no | Fix the request body. |
+| 409 | `mode_mismatch` | no | Notion isn't delegated. Re-read `integrations.md` and stop. |
+| 409 | `precondition` | no | Mode/backend flipped during the queue wait. Re-check state. |
+| 429 | `task_quota_exhausted` | no | Daily cap reached. Wait or surface. |
+| 502 | `parse_error` / `schema_violation` | no (daemon already retried once) | Simplify schema. |
+| 502 | `tool_unavailable` | no | No connector tool fits. Surface the gap. |
+| 502 | `tool_failed` | maybe | Connector tool returned an error. Surface verbatim. |
+| 502 | `auth_error` | no | Connector signed out. Re-authenticate. |
+| 502 | `policy_violation` | no | Subprocess attempted an out-of-allowlist tool (anti-injection). |
+| 502 | `loop_aborted` | no | `maxToolCalls` exceeded. Bump or simplify. |
+| 502 | `budget_exhausted` | no | `maxBudgetUsd` exceeded. Caller can raise the cap. |
+| 502 | `post_write_format_failure` | no | Write succeeded; formatting failed. Surface with partial trace. |
+| 503 | `delegated_proxy_busy` | yes | Queue saturated. Backoff and retry once. |
+| 503 | `task_mode_disabled` | no | Operator killed it. Stop. |
+| 504 | `timeout` | yes (1×) | Wall-clock fired. Retry once. |
+| 500 | `subprocess_crashed` | no | Daemon-side defect. Surface and stop. |
+Always preserve `body.message` verbatim when reporting to the user.
+## 8. Owner notification (opt-in)
+```bash
+curl -sS -X POST http://localhost:8321/api/notify \
+  -H 'Content-Type: application/json' \
+  -d '{"message": "Archived 7 stale pages under the <db> database."}'
+```
+Do not call `/api/notify` for routine reads or single-page edits.
+## 9. Cost attribution
+Every `/exec` writes one row to `agent_actions` with
+`action_type='delegated_task.exec'`, full token + USD breakdown, and
+the parent `event_id` / `processKey`. Retrospective calls
+(`GET /api/agent/actions?kind=delegated_task.exec`) surface exactly
+what was spent.

package/agent-assets/skills/notion/SKILL.md ADDED Viewed

@@ -0,0 +1,86 @@
+---
+name: notion
+description: Load when the user mentions Notion or the agent needs to read, query, search, create, update, or archive Notion pages and databases. Mail is in `mail`; Calendar / external Obsidian / GitHub in `external-services`; scheduling in `schedule`.
+allowed-tools:
+  - Bash(curl *)
+  - Bash(jq *)
+  - Read
+---
+# Notion API Reference
+Base URL: `http://localhost:8321`. All calls via `curl -s` with
+`Content-Type: application/json` on POST/PATCH/PUT. URL-encode spaces in paths.
+Full CRUD over Notion pages plus workspace search. Reads and writes are
+Autonomous; writes are still serialized per-process and pre-marked
+`notion:<pageId>` for write attribution. The daemon does not DM the
+owner before a write — the user's `deniedTools` setting is the gate.
+Call `POST /api/notify` yourself when you judge the user would
+want immediate awareness.
+**Parent shorthand**: `parent` accepts a label string (`"tasks"`),
+`{ database: "tasks" }`, `{ data_source_id }`, `{ database_id }`, or
+`{ page_id }`. Resolve labels via `GET /api/notion/databases` first.
+## Read operations
+```bash
+curl -s http://localhost:8321/api/notion/databases                          # list configured DBs
+curl -s "http://localhost:8321/api/notion/query?database=tasks"             # query a database
+curl -s "http://localhost:8321/api/notion/query?database=tasks&filter=..."  # filtered (URL-encoded JSON)
+curl -s "http://localhost:8321/api/notion/search?q=launch+plan"             # search workspace
+curl -s http://localhost:8321/api/notion/pages/abc123...                    # retrieve page
+```
+Pagination: `page_size` (1–100, default 20) + `start_cursor` from response's
+`next_cursor`. Check `has_more` to know if more pages exist.
+## Create a page (write — Autonomous)
+```bash
+curl -s -X POST http://localhost:8321/api/notion/pages \
+  -H 'Content-Type: application/json' \
+  -d '{"parent": "tasks", "properties": {"Name": {"title": [{"text": {"content": "Review roadmap"}}]}, "Status": {"status": {"name": "Todo"}}}, "markdown": "## Context\n\nDetails."}'
+```
+## Update page properties (write — Autonomous)
+```bash
+curl -s -X PATCH http://localhost:8321/api/notion/pages/abc123... \
+  -H 'Content-Type: application/json' \
+  -d '{"properties": {"Done": {"checkbox": true}, "Status": {"status": {"name": "Done"}}}}'
+```
+## Update page content (write — Autonomous)
+**Concurrency warning**: Notion v5 has no etags. If another client edits
+between GET and PATCH, `oldStr` may fail silently. For high-risk edits,
+prefer `mode=replace_all`.
+Modes: `append`, `replace_all`, `update` (find-and-replace via
+`updates: [{oldStr, newStr}]`).
+```bash
+curl -s -X PATCH http://localhost:8321/api/notion/pages/abc123.../content \
+  -H 'Content-Type: application/json' \
+  -d '{"mode": "append", "content": "\n## Follow-ups\n- Call vendor"}'
+```
+## Archive a page (write — Autonomous)
+```bash
+curl -s -X DELETE http://localhost:8321/api/notion/pages/abc123...
+```
+Moves to trash (~30 days). Restore via `PATCH` with `{ "in_trash": false }`.
+## When NOT to act
+- During `routine.hourly_check` this skill is **read-only** — no creates,
+  property updates, content patches, or archives.
+- No bulk operations without user confirmation.
+- Writes are Autonomous; the daemon does not DM the owner. Single ops
+  only — the agent's own judgment is the gate, not the daemon. If you're
+  about to update 3+ pages at once, stop and ask the user. Call
+  `POST /api/notify` when the user would want immediate awareness.

package/agent-assets/skills/observations/SKILL.md ADDED Viewed

@@ -0,0 +1,234 @@
+---
+name: observations
+description: Load when a session needs to drain the pending-observations queue or inspect raw external-source state (Obsidian edits, new git commits, Notion updates) and optionally mark entries consumed.
+allowed-tools:
+  - Bash(curl *)
+  - Read
+---
+# Observations Review & Source Access
+## Workflow
+1. Fetch pending user-originated observations:
+   `curl -s "http://localhost:8321/api/observations?pending=true&actor=user&limit=20"`
+2. Group related observations before acting.
+3. For each group, apply the **fetch decision** (below) — `summary_text` + `novelty_score` are pre-computed by the daemon's per-observation summarizer; only `novelty_score >= 2` warrants full content fetch.
+4. Decide actionability:
+   - Update `today.md` for TODOs, blockers, decisions, or deadlines
+   - Update `roadmap.md` or `projects/*.md` only for material project-state changes
+   - Schedule a wake-up if the observation implies a future reminder
+5. Apply the smallest meaningful set of context updates.
+6. Mark processed observations consumed:
+   `curl -s -X POST http://localhost:8321/api/observations/consume -H 'Content-Type: application/json' -d '{"ids":[1,2],"correlationId":"<event-correlation-id>"}'`
+## Skip Criteria
+- Journal-only edits with no actionable follow-up
+- Formatting-only churn / auto-generated files / index refreshes
+- Agent-originated changes (already filtered via `actor=user`)
+## Actionable Criteria
+- New TODO/FIXME items or explicit deadlines affecting current work
+- Meeting notes with decisions or blockers
+- Project milestones or status changes worth reflecting in roadmap/projects
+**Cost:** Prefer one grouped patch over many small writes. If all noise, just log that you reviewed.
+---
+## Fetch Decision Guide
+The daemon pre-summarizes every observation with a per-source LLM call (lite tier) and writes `summary_text` (≤120 chars) + `novelty_score` (0–3) onto the row. Use those signals as your primary input — fetch full content **only** when the score warrants it.
+### Tiered consumption (cost-reduction-structural §A)
+| `summary_status` / `novelty_score` | Action | Notes |
+|---|---|---|
+| `summary_status === 'done'` AND `novelty_score >= 2` AND `summaryStale === false` | **Fetch full** if needed; route to today.md / projects / roadmap | High-signal — usually justifies the round-trip |
+| `summary_status === 'done'` AND `novelty_score === 1` AND `summaryStale === false` | **Use `summary_text` only** | Minor — no fetch unless cross-referenced by another observation in the same batch |
+| `summary_status === 'done'` AND `novelty_score === 0` AND `summaryStale === false` | **Silently consume** | Noise — log only when aggregating |
+| `summaryStale === true` | Treat as if `summary_status !== 'done'` — fall back to legacy fetch-on-doubt | Summary aged out (>6h since observed_at); content may have drifted under it |
+| `summary_status !== 'done'` (pending/skipped/failed/null) | Fall back to legacy fetch-on-doubt below | Summarizer disabled, lagging, or crashed |
+**Hard rule:** never fetch raw content when `novelty_score < 2`, unless a different observation in the same batch references the same path/ref OR `summaryStale === true`. This is the primary lever for hourly_check cost reduction.
+### Legacy fetch-on-doubt (used when `summary_status !== 'done'`)
+Before fetching, ask: **"If I fetch this, will my next action actually differ from what I'd do now?"** No → don't fetch. Yes → fetch. Fetching for "verification" wastes tokens; fetching to resolve ambiguity is what these endpoints exist for.
+| Situation | Action | Why |
+|---|---|---|
+| Preview contains TODO, deadline, or concrete task reference | **Act on preview** | You have what you need |
+| Preview is truncated on a relevant section | **Fetch full** | Missing load-bearing content |
+| Preview is empty or says `(file read failed)` | **Fetch full** | Preview is broken, not empty |
+| Change type is `deleted` | **Log only — no fetch** | Nothing to read |
+| Journal/diary entry with no task markers visible | **Skip entirely** | Usually no action needed |
+| Active project file with ambiguous preview | **Fetch full** | Active project justifies cost |
+| Clear commit message + small/routine diff | **Act on preview** | Common refactors, renames |
+| Generic commit message ("update","fix","wip") + multi-file | **Fetch full diff** | Vague message requires actual change |
+**Availability:** Obsidian → 503 when app not running (fall back to preview); Git → 400 for repos not in `PA_GIT_REPOS`; Notion → empty for unconfigured DBs.
+---
+## Observation Review Logging
+Hourly check and Morning Routine review pending observations in aggregate. Even when nothing is surfaced, the review must remain auditable.
+### observations → Agent Log
+Section: `agent_log` · Mode: `append` · Format: `- HH:MM [observations] summary_of_review`
+Examples:
+- `- 09:35 [observations] reviewed 6 pending changes, added 2 tasks from Obsidian, skipped 4 as non-actionable`
+- `- 16:08 [observations] reviewed 5 changes, no actionable updates`
+Skip reasons: `skipped (personal journal)`, `skipped (auto-generated)`, `skipped (no actionable content)`, `skipped (routine note)`.
+---
+## API Reference — Observations
+### GET /api/observations
+```bash
+curl -s "http://localhost:8321/api/observations?pending=true&actor=user&limit=20"
+```
+Params: `pending` (bool, default true), `actor` (user/agent/system/unknown), `limit` (1-100, default 20), `offset`, `source` (prefix match — e.g. `obsidian`, `obsidian:primary`, `obsidian:external`, `git`, `calendar`), `since` (ISO 8601).
+The `source` filter is a prefix match: `source=obsidian` returns rows from both the primary management vault (`obsidian:primary`) and the external note vault (`obsidian:external`). Narrow to one side with the namespaced form when the distinction matters — typically `obsidian:primary` refers to the agent's own files and most user-actionable edits come from `obsidian:external`.
+Response: `{ "observations": [{ "id", "source", "ref", "changeType", "actor", "observedAt", "payload", "consumedAt?", "consumedBy?", "summaryText?", "noveltyScore?", "summaryStatus?", "summaryAt?", "summaryStale" }], "limit", "offset", "pending" }`
+`summaryText` / `noveltyScore` are populated asynchronously by the per-observation summarizer (cost-reduction-structural §A). When `summaryStatus !== 'done'` the row may have been skipped (deny-list, agent-actor) or the summarizer hasn't caught up yet — fall back to the legacy fetch-on-doubt rules in that case. `summaryStale === true` flags summaries older than 6 h relative to `observedAt`; treat them the same way as a missing summary.
+### POST /api/observations
+Record an agent-queued observation (only `actor: "agent"` or `"system"`
+accepted — user-authored observations arrive through the vault / mail
+watchers, never this route). Used by `routine.hourly_check` to queue
+`roadmap_candidate` signals the next `routine.roadmap_refresh` consumes.
+```bash
+curl -s -X POST http://localhost:8321/api/observations \
+  -H 'Content-Type: application/json' \
+  -d '{"source":"roadmap_candidate:travel","ref":"trip-portland-2026-summer","changeType":"created","actor":"agent","payload":{"note":"DM mentioned Portland trip this summer"}}'
+```
+`(source, ref)` is the idempotency key — re-posting the same pair while
+the prior row is still pending **updates** the payload rather than
+creating a duplicate. Subkind suffixes after the colon are by
+convention (`roadmap_candidate:calendar`, `roadmap_candidate:vault`,
+etc.) and are picked up by the prefix match on the GET route.
+### POST /api/observations/consume
+```bash
+curl -s -X POST http://localhost:8321/api/observations/consume \
+  -H 'Content-Type: application/json' \
+  -d '{"ids": [1, 2, 3], "correlationId": "<event_correlation_id>"}'
+```
+Response: `{ "consumed": 3 }`
+### GET /api/observations/stats
+`curl -s http://localhost:8321/api/observations/stats` → `{ "total", "pending", "bySource": {...}, "byActor": {...} }`
+---
+## External Source Read Endpoints
+Use when the fetch decision says to retrieve full content. These access the
+**external** Obsidian vault, Git repos, and Notion — not the agent's primary
+management vault. Primary-vault reads and writes go through `/api/context/*`
+(see the `context` skill).
+### Obsidian (external vault)
+```bash
+curl -s http://localhost:8321/api/obsidian/status
+curl -s "http://localhost:8321/api/obsidian/search?q=meeting+notes&limit=10"
+curl -s http://localhost:8321/api/obsidian/notes/Daily%20Notes/2026-04-06  # URL-encode spaces, omit .md
+```
+### Git
+Only repos in `PA_GIT_REPOS`. Use `repoPath` from event data.
+```bash
+curl -s "http://localhost:8321/api/git/log?repo=/path/to/repo&count=5"
+curl -s "http://localhost:8321/api/git/diff?repo=/path/to/repo&ref=HEAD~3..HEAD"
+curl -s "http://localhost:8321/api/git/show?repo=/path/to/repo&hash=abc1234"
+```
+### Notion
+The wire surface depends on Notion's integration mode (read
+`<integration_modes>` injected above). Pick the branch that matches the
+current state.
+<!-- mode:direct:notion -->
+```bash
+curl -s "http://localhost:8321/api/notion/query?databaseId=xxx"
+```
+<!-- /mode:direct:notion -->
+<!-- mode:delegated-same:notion -->
+The `/api/notion/query|search|pages` routes return 410 in delegated
+mode. Use your session backend's native Notion MCP tool — the
+connector is signed in directly on this backend, no daemon proxy is
+involved. Resolve `<databaseId>` first by reading the un-gated
+`/api/notion/databases` config dump
+(`curl -s http://localhost:8321/api/notion/databases`) and then pass
+the UUID to the connector's data-source / search tool:
+| session backend | structured filter (data-source query)              | listing fallback (no filter support)         | workspace search        |
+|-----------------|----------------------------------------------------|----------------------------------------------|-------------------------|
+| claude          | n/a — connector has no filtered query              | `mcp__claude_ai_Notion__notion-fetch`        | `mcp__claude_ai_Notion__notion-search` |
+| codex           | `mcp__codex_apps__notion._notion_query_data_sources` | `mcp__codex_apps__notion._fetch`           | `mcp__codex_apps__notion._search`      |
+| gemini          | n/a — connector has no filtered query              | `mcp_notion_notion-fetch`                    | `mcp_notion_notion-search`             |
+For Claude / Gemini sessions: call the listing tool against the data
+source and post-filter in this skill (the structured-filter capability
+is Codex-only). For Codex sessions: pass the SQLite-style `WHERE`
+clause directly to `_notion_query_data_sources`. See the `notion`
+skill body for full property-naming and write-tier conventions.
+<!-- /mode:delegated-same:notion -->
+<!-- mode:delegated-cross:notion -->
+The `/api/notion/query|search|pages` routes return 410 in delegated
+mode and your own backend's native Notion connector (if signed in)
+reads a different workspace than the user's delegated one. Call the
+daemon's `/exec` task endpoint with a natural-language intent — the
+daemon spawns the delegated backend's subprocess and lets it pick
+the right connector primitive whichever backend currently owns
+Notion. Resolve `<databaseId>` first via
+`curl -s http://localhost:8321/api/notion/databases` (the config-dump
+path is un-gated), then:
+```bash
+curl -s -X POST http://localhost:8321/api/integrations/notion/exec \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "task": "Fetch the most recent <N> pages in the <DB-LABEL> database (data source <UUID>). For each return id, title, lastEditedAt, and any Status property.",
+    "outputSchema": { "type": "object", "required": ["pages"], "properties": { "pages": { "type": "array", "items": { "type": "object", "required": ["id","title","lastEditedAt"] } } } },
+    "maxToolCalls": 5,
+    "cacheable": true
+  }'
+```
+Do NOT call `/api/notion/{query,search,pages}` directly (returns
+410), and do NOT fall back to your own backend's native Notion MCP
+tools — that connector reads a different workspace than the user's
+delegated one.
+<!-- /mode:delegated-cross:notion -->
+<!-- mode:disabled:notion -->
+Notion is disabled — there is no live source. Treat the observation
+as preview-only and proceed without a Notion fetch.
+<!-- /mode:disabled:notion -->
+## Source namespacing (auto-curated)
+<!-- CURATION:convention_notes id="source-namespacing" -->

package/agent-assets/skills/observations/curation.json ADDED Viewed

@@ -0,0 +1,13 @@
+{
+  "version": 1,
+  "sections": [
+    {
+      "id": "source-namespacing",
+      "kind": "convention_notes",
+      "anchor": "<!-- CURATION:convention_notes id=\"source-namespacing\" -->",
+      "human_label": "Observation source namespacing",
+      "description": "Source string conventions: prefix grammar, sub-kind suffixes, idempotency key shape",
+      "scope_paths": ["agent-journal.md"]
+    }
+  ]
+}

package/agent-assets/skills/observations/seeds/source-namespacing.seed.json ADDED Viewed

@@ -0,0 +1,20 @@
+{
+  "kind": "convention_notes",
+  "notes": [
+    {
+      "topic": "Source prefix",
+      "rule": "Observation source strings carry a kind prefix followed by an optional colon-separated sub-kind: kind[:sub_kind][:detail].",
+      "example": "obsidian:primary, obsidian:external, roadmap_candidate:travel"
+    },
+    {
+      "topic": "Obsidian split",
+      "rule": "obsidian:primary covers the agent's own management vault; obsidian:external covers user note vaults watched separately.",
+      "example": "source=obsidian matches both via the prefix filter on GET /api/observations"
+    },
+    {
+      "topic": "Idempotency key",
+      "rule": "The pair (source, ref) is the idempotency key on POST /api/observations and a re-post of the same pair updates the pending row instead of duplicating it.",
+      "example": "source=roadmap_candidate:travel ref=trip-portland-2026-summer"
+    }
+  ]
+}

package/agent-assets/skills/project-doc/SKILL.md ADDED Viewed

@@ -0,0 +1,86 @@
+---
+name: project-doc
+description: Create and maintain Git-backed project and repository context documents through the daemon context API only.
+allowed-tools:
+  - Bash(curl *)
+  - Bash(git -C *)
+---
+# Project Doc
+Use this skill for Git-backed context documents under the unified
+repositories layout (see
+`docs/design/appendices/unified-repositories.md` §4.5):
+- **Git-managed repositories** (any classification) write to
+  `git/<slug>/overview.md` plus per-day `git/<slug>/journal/<YYYY-MM-DD>.md`.
+- **Non-git project pages** (manual projects without a backing repo)
+  still live at `projects/<slug>.md` per the original layout.
+The pre-cutover paths `projects/<slug>.md` (for git-backed projects)
+and `git-repos/<slug>.md` are **retired** — every git-managed repo
+now lives under `git/<slug>/`. Classification (`project` vs `repo-only`)
+no longer changes the path; it controls which sections the overview
+carries (project keeps `## Lifecycle Phases`, repo-only stays light).
+## Hard rules
+- Write only through `/api/context/*`. Never edit files directly on disk.
+- Do not modify `today.md`, `roadmap.md`, `user/*`, `rules/*`, or
+  unrelated context files.
+- Preserve valid frontmatter. The overview file uses `type: git-project`,
+  the journal file uses `type: git-journal`. Both carry an ISO `updated`
+  date.
+- Use `GET /api/context/<path>` before updating an existing overview.
+  Use `PUT /api/context/<path>` for initialization or full-document
+  updates. Use `PATCH` only when appending to a section without touching
+  frontmatter.
+- Preserve user prose, manual notes, and existing headings. Compress
+  old Git history instead of deleting meaningful context.
+## Overview file shape (`git/<slug>/overview.md`)
+- Frontmatter: `type: git-project`, `repository_id`, `slug`,
+  `github_repo` (or null), `local_path`, `classification`, `category`,
+  `created`, `updated`.
+- `# <display name>`
+- `## Summary`
+- `## Architecture`
+- `## Notable Changes`
+- `## Lifecycle Phases` (project classification only)
+- `## Open Threads` (manual prose; preserved verbatim)
+- `## Daily Activity Log` (rolling 30-day window)
+## Journal file shape (`git/<slug>/journal/<YYYY-MM-DD>.md`)
+- Frontmatter: `type: git-journal`, `repository_id`, `date`,
+  `commit_count`, `pr_events`, `workflow_events`.
+- `# <date> — <slug>`
+- `## Commits`
+- `## PR / Workflow Events`
+- `## Files Changed`
+## Placeholder substitution
+When the template carries placeholders, replace every one before
+writing:
+- `{updated}` / `{created}`: current ISO date, `YYYY-MM-DD`.
+- `{slug}`: `task_context.slug` (deterministic, sanitized).
+- `{repository_id}`: `task_context.repositoryId`.
+- `{local_path}`: `task_context.localPath`.
+- `{github_repo}`: `task_context.githubRepo` or `null`.
+- `{classification}`, `{category}`: values from `task_context`.
+- `{display_name}`: pretty-printed slug or `task_context.displayName` if
+  the row has one.
+- `{date}`, `{commit_count}`, `{pr_events}`, `{workflow_events}`,
+  `{commits_list}`, `{pr_workflow_summary}`, `{files_summary}`: derived
+  from Git evidence collected for the journal day.
+## Project / git-project file shape (auto-curated)
+<!-- CURATION:knowledge_layout id="project-shape" -->
+## Slug grammar (auto-curated)
+<!-- CURATION:convention_notes id="slug-grammar" -->

package/agent-assets/skills/project-doc/curation.json ADDED Viewed

@@ -0,0 +1,21 @@
+{
+  "version": 1,
+  "sections": [
+    {
+      "id": "project-shape",
+      "kind": "knowledge_layout",
+      "anchor": "<!-- CURATION:knowledge_layout id=\"project-shape\" -->",
+      "human_label": "Project / git-repo file shape",
+      "description": "Required sections in projects/*.md and git-repos/*.md, and what each section holds",
+      "scope_paths": ["projects/*.md", "git-repos/*.md"]
+    },
+    {
+      "id": "slug-grammar",
+      "kind": "convention_notes",
+      "anchor": "<!-- CURATION:convention_notes id=\"slug-grammar\" -->",
+      "human_label": "Project slug grammar",
+      "description": "Slug format, length cap, reserved stems",
+      "scope_paths": ["projects/*.md", "git-repos/*.md"]
+    }
+  ]
+}