@aitne-sh/aitne 0.1.7 → 0.1.8

package/agent-assets/skills/external-services/SKILL.md

@@ -3,7 +3,6 @@ name: external-services
 description: Load for calendar work (Google Calendar, Outlook Calendar, OR Apple Calendar / iCloud), the user's external Obsidian vault, GitHub, or user-authored Skills management. Mail lives in `mail`; Notion in `notion`; one-shot and recurring scheduling in `schedule`.
 allowed-tools:
   - Bash(curl *)
-  - Bash(jq *)
   - Read
 ---
 
@@ -81,261 +80,23 @@ direct route when not.
 
 ---
 
-<!-- service:calendar -->
-## Calendar
-
-Google Calendar proxy. Operates on the user's primary calendar (configurable via `calendarId` param).
-
-**Timezone rule**: Always include a TZ offset in `start`/`end` dateTime values (e.g. `-04:00`). All-day events use `YYYY-MM-DD` (no TZ needed).
-
-**Event status**: GET returns deleted events with `status: "cancelled"` (200, not 404). Always check `status` before acting. The list endpoint automatically excludes cancelled events.
-
-### List events
-```bash
-curl -s "http://localhost:8321/api/calendar/events?date=today&days=3"
-```
-
-### Get event detail
-```bash
-curl -s "http://localhost:8321/api/calendar/events/abc123eventid"
-```
-**Always GET before PATCH** to see current state and attendees.
-
-### Create event (write — Autonomous)
-```bash
-curl -s -X POST "http://localhost:8321/api/calendar/events" \
-  -H 'Content-Type: application/json' \
-  -d '{"summary": "Team meeting", "start": "2026-04-02T14:00:00-04:00", "end": "2026-04-02T15:00:00-04:00"}'
-```
-Optional: `description`, `location`, `reminders`, `recurrence`, `attendees`, `visibility`. All-day: `YYYY-MM-DD`. Attendees: add `?sendUpdates=all` to notify. RRULE: `RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR`.
-
-### Update event (write — Autonomous; commonly on the starter denylist)
-```bash
-curl -s -X PATCH "http://localhost:8321/api/calendar/events/abc123" \
-  -H 'Content-Type: application/json' \
-  -d '{"start": "2026-04-02T15:00:00-04:00", "end": "2026-04-02T16:00:00-04:00"}'
-```
-For recurring events, use the instance ID to update a single occurrence — never PATCH the master.
-
-**ATTENDEES WARNING**: PATCH with `attendees` **replaces the entire list** — it does NOT append. To add one attendee: (1) GET, (2) copy existing, (3) add new, (4) PATCH full list.
-
-### Delete event (write — Autonomous; default starter denylist denies it)
-```bash
-curl -s -X DELETE "http://localhost:8321/api/calendar/events/abc123"
-```
-Add `?sendUpdates=all` to notify attendees. Do NOT PATCH a cancelled event.
-
-### List calendars
-```bash
-curl -s http://localhost:8321/api/calendar/calendars
-```
-
-### Free/busy query
-```bash
-curl -s -X POST http://localhost:8321/api/calendar/freebusy \
-  -H 'Content-Type: application/json' \
-  -d '{"timeMin": "2026-04-11T09:00:00-04:00", "timeMax": "2026-04-11T18:00:00-04:00"}'
-```
-
-### Calendar error envelope (direct mode)
-
-| HTTP | `error` | What it means / what to do |
-|---|---|---|
-| 400 | `validation_error` | Bad request shape (e.g. missing `start`/`end`, malformed RRULE). Fix and retry. |
-| 404 | `not_found` | Event id unknown or already deleted. Re-list before retrying. |
-| 410 | `integration_delegated` | Calendar flipped to delegated mode mid-session. This skill body is direct-only — re-read `integrations.md` and use `POST /api/integrations/google_calendar/exec` (cross-backend task mode) or your session backend's native Calendar MCP (the same-backend variant) instead. |
-| 502 | `calendar_error` | Upstream Google API error — `message` carries the API's text. Surface verbatim; do not retry unless clearly transient. |
-| 503 | `calendar_not_configured` | Direct OAuth credentials are missing or the user has disabled Calendar in settings. Tell the user and stop. |
-<!-- /service:calendar -->
+{{> ref:calendar-google }}
 
 ---
 
-<!-- service:outlook-calendar -->
-## Outlook Calendar (Microsoft Graph)
-
-Use this section **only when `rules/management.md` Schedule = Outlook Calendar**. The provider-routing table at the top of this skill is non-negotiable.
-
-v1 is **read-only and on-demand** — there is no Outlook calendar poller, so `schedule.approaching` events do not fire for Outlook calendars (the user's own Outlook clients fill that gap). Write surfaces (create / update / delete) are deferred. If the user asks the agent to schedule or change an Outlook event, tell them you can read the calendar but must defer the write to them.
-
-OAuth is **shared with Outlook Mail** via the same MSAL cache row (`mail:outlook:<accountId>`) — if Outlook Mail is configured `direct` and authenticated, calendar reads succeed with no second consent.
-
-### List events
-```bash
-curl -s "http://localhost:8321/api/calendar/outlook/events?date=today&days=3"
-```
-Same query params as Google (`date`: `YYYY-MM-DD` or `today`; `days`: 1–90; optional `calendarId`). Returns `{ events: [...], accountId }`.
-
-### List calendars
-```bash
-curl -s http://localhost:8321/api/calendar/outlook/calendars
-```
-Returns `{ calendars: [...], accountId }`. The user's primary calendar is marked `primary: true`.
-
-### Outlook Calendar error envelope
-
-| HTTP | `error` | What it means / what to do |
-|---|---|---|
-| 400 | bad query | Malformed `date` or `days` value. |
-| 502 | `calendar_error` | Upstream Microsoft Graph error — `message` carries wire text. |
-| 503 | `outlook_not_configured` | No authenticated Outlook account. Direct OAuth credentials missing. |
-| 503 | `outlook_calendar_disabled` | The user toggled Outlook Calendar off in Settings → Calendar. Tell the user and stop. |
-<!-- /service:outlook-calendar -->
+{{> ref:calendar-outlook }}
 
 ---
 
-<!-- service:apple-calendar -->
-## Apple Calendar (iCloud CalDAV)
-
-Use this section **only when `rules/management.md` Schedule = Apple Calendar**. The provider-routing table at the top of this skill is non-negotiable.
-
-The route shape mirrors `/api/calendar/*` so prose patterns transfer: list → get → patch / create / delete. Differences are flagged below.
-
-### Probe configuration before first use
-```bash
-curl -s http://localhost:8321/api/apple-calendar/status
-# → { "configured": bool, "available": bool }
-```
-- `configured: false` → user has not entered Apple ID + app-specific password yet. Tell the user to open the dashboard's Apple Calendar card (Connections page) and paste a password from `appleid.apple.com` → Sign-In and Security → App-Specific Passwords. **Do not try to read or write events** until `available: true`.
-- `configured: true, available: false` → credentials are stored but iCloud rejected the last connection. Surface verbatim; common cause is the user revoked the app-specific password.
-
-### List events
-```bash
-curl -s "http://localhost:8321/api/apple-calendar/events?date=today&days=3"
-```
-Same query params as Google: `date` (`YYYY-MM-DD` or `today`), `days` (max 90). Returns `{ events: [...] }` with the same JSON shape used by the Google route — `id`, `summary`, `start`, `end`, `location`, `description`, `allDay`, `status`, plus two Apple-specific fields:
-- `recurring` (bool) — true for any event in a recurring series.
-- `recurrenceId` (string|null) — populated for an expanded instance of a series.
-
-For a recurring instance the `id` is `<UID>__<RECURRENCE-ID>` so you can address a specific occurrence.
-
-**Timezones**: dateTime values are emitted in UTC (`Z` suffix). Convert to the user's local timezone before showing them.
-
-### Get event detail
-```bash
-curl -s "http://localhost:8321/api/apple-calendar/events/<id>"
-```
-Always GET before PATCH so you see the current summary/start/end.
-
-### Create event (write — Autonomous)
-```bash
-curl -s -X POST http://localhost:8321/api/apple-calendar/events \
-  -H 'Content-Type: application/json' \
-  -d '{"summary": "Team meeting", "start": "2026-04-26T14:00:00+09:00", "end": "2026-04-26T15:00:00+09:00"}'
-```
-Optional: `description`, `location`. **[Apple only]** `attendees`, `reminders`, `recurrence`, `visibility` from the Google shape are accepted by the Zod schema but are silently dropped — iCloud invitations and reminder defaults belong to the user's Apple ID and the agent should not author them. If a user asks for those, tell them and stop.
-
-### Update event (write — Autonomous)
-```bash
-curl -s -X PATCH http://localhost:8321/api/apple-calendar/events/<id> \
-  -H 'Content-Type: application/json' \
-  -d '{"start": "2026-04-26T15:00:00+09:00", "end": "2026-04-26T16:00:00+09:00"}'
-```
-
-**[Apple only] Recurring-event editing semantics — read before writing**
-- A composite id (one whose suffix matches `__YYYY-MM-DD…`) addresses **one occurrence** of a series. PATCH/DELETE on it returns `501 recurring_instance_unsupported`. To move a single occurrence the user must edit it from Calendar.app.
-- A bare id whose GET returned `recurring: true` is the **series master**. PATCH on the master shifts the **entire series** (every future occurrence moves), and DELETE removes the entire series. Confirm with the user that they intend a series-level edit before issuing the call — agents have historically read "PATCH this event's start" as a single-instance reschedule, which is wrong here.
-- A bare id with `recurring: false` is a normal one-off event — PATCH/DELETE behave as usual.
-- `summary`, `start`, and `end` may be updated independently. Toggling all-day-ness (`YYYY-MM-DD` ↔ `…T…Z`) requires providing **both** `start` and `end` in the same PATCH; the codec rejects partial all-day toggles with `400 validation_error`.
-- Time strings must include a TZ offset (`Z` or `±HH:MM`); naked ISO without offset returns `400 validation_error` — do not interpret a user-stated time as local without an explicit offset.
-
-### Delete event (write — Autonomous)
-```bash
-curl -s -X DELETE http://localhost:8321/api/apple-calendar/events/<id>
-```
-Same recurring semantics as PATCH (see the rules block above).
-
-### List calendars
-```bash
-curl -s http://localhost:8321/api/apple-calendar/calendars
-# → { "calendars": [{ id, summary, description, primary }, ...] }
-```
-The `id` is an opaque CalDAV URL. The user's primary calendar is marked `primary: true`. To change which calendar create/list reads, see the dashboard Apple Calendar card.
-
-### Free/busy query
-```bash
-curl -s -X POST http://localhost:8321/api/apple-calendar/freebusy \
-  -H 'Content-Type: application/json' \
-  -d '{"timeMin": "2026-04-26T09:00:00Z", "timeMax": "2026-04-26T18:00:00Z"}'
-```
-**[Apple only]** Free-busy is derived from `listEvents` — events with `status: "cancelled"` are excluded. `calendarIds` is ignored (the primary calendar is the only target).
-
-### Apple Calendar error envelope
-
-| HTTP | `error` | What it means / what to do |
-|---|---|---|
-| 400 | `validation_error` | Bad request shape. Fix and retry. |
-| 401 | `auth_failed` | iCloud rejected the credentials. Tell the user to refresh the app-specific password in the dashboard. |
-| 404 | `not_found` | Event id unknown or already deleted. Re-list before retrying. |
-| 501 | `recurring_instance_unsupported` | The id targets a single occurrence of a recurring series — see the PATCH/DELETE notes above. |
-| 502 | `apple_calendar_error` | Upstream iCloud / CalDAV error. `message` carries the wire text. |
-| 503 | `apple_calendar_not_configured` | Credentials missing or last connection failed. Run the status probe above. |
-
-### Known gap: no proactive notifications
-
-The hourly polling pivot (`schedule.approaching` events, observation deltas) only fires for Google Calendar today. With Apple Calendar selected, on-demand DM queries work but the agent will not proactively warn about an imminent event — the user's own iOS / macOS Calendar.app notifications fill that gap.
-<!-- /service:apple-calendar -->
+{{> ref:calendar-apple }}
 
 ---
 
-<!-- service:obsidian -->
-## Obsidian (external vault)
-
-**Scope**: this skill targets a **separate** Obsidian vault the user maintains
-alongside this app — e.g. a personal knowledge base. It is **not** the agent's
-own primary management store. The agent's primary files (`today.md`,
-`roadmap.md`, `projects/`, `rules/`, `routines/`, `user/`, `agent/`, …) live
-in the primary vault and are reached via `/api/context/*` (see the `context`
-skill). **Never** use this skill to read or write the primary vault.
-
-Use this skill when the user asks the agent to look up, append to, or create
-notes inside their external knowledge vault — never for the agent's own
-working state.
-
-Output language: follow `<output_language_policy>` (Policy C — body
-and any new headings the agent creates are in `<settings primary_language>`).
-Preserve verbatim any path / file-name patterns the user has established.
-
-Full CRUD over the external vault. Requires the Obsidian app running (the
-CLI proxies through it). Omit `.md` extension from paths. All writes are
-Autonomous; the daemon does not DM the owner before/after the call. Call
-`POST /api/notify` yourself when the user would want to know.
-
-```bash
-curl -s http://localhost:8321/api/obsidian/status                            # external vault availability
-curl -s "http://localhost:8321/api/obsidian/search?q=meeting+notes&limit=10" # search external vault
-curl -s http://localhost:8321/api/obsidian/notes/Daily%20Notes/2026-04-06    # read external note
-curl -s -X POST http://localhost:8321/api/obsidian/notes \
-  -H 'Content-Type: application/json' \
-  -d '{"name": "Meeting Notes 2026-04-02", "content": "# Meeting\n..."}'    # create external note (fails if exists)
-curl -s -X PUT http://localhost:8321/api/obsidian/notes/Projects/ProjectA \
-  -H 'Content-Type: application/json' -d '{"content": "# Full body"}'       # create-or-overwrite external note
-curl -s -X PATCH http://localhost:8321/api/obsidian/notes \
-  -H 'Content-Type: application/json' \
-  -d '{"file": "Meeting Notes 2026-04-02", "content": "\n- Action item"}'   # append to external note
-curl -s -X PATCH http://localhost:8321/api/obsidian/daily \
-  -H 'Content-Type: application/json' -d '{"content": "- [ ] Follow up"}'   # append to external daily note
-curl -s -X DELETE http://localhost:8321/api/obsidian/notes/Projects/Old      # delete from external vault (moves to trash)
-```
-**Endpoint choice**: Read → GET, Create-only → POST, Edit → PUT, Append → PATCH.
-
-If the user's request is really about the agent's own state (today, roadmap,
-projects, journal, rules, routines, user profile), switch to the `context`
-skill and the `/api/context/*` endpoints instead.
-<!-- /service:obsidian -->
+{{> ref:obsidian }}
 
 ---
 
-<!-- service:github -->
-## GitHub
-
-```bash
-curl -s http://localhost:8321/api/github/repos                              # list watched repos
-curl -s "http://localhost:8321/api/github/pulls?owner=user&repo=repo&state=open" # list PRs
-curl -s -X POST http://localhost:8321/api/github/pulls/comment \
-  -H 'Content-Type: application/json' \
-  -d '{"owner": "user", "repo": "repo", "pull_number": 42, "comment": "LGTM"}' # comment — Autonomous
-```
-<!-- /service:github -->
+{{> ref:github }}
 
 ---
 
@@ -360,18 +121,4 @@ flows.
 
 ---
 
-## Skills Management
-
-User-authored skills: `~/.personal-agent/skills/{slug}/SKILL.md`. Built-in skills are read-only (403). Slug: lowercase kebab-case `[a-z0-9][a-z0-9-]*`, 1–64 chars.
-
-```bash
-curl -s http://localhost:8321/api/skills                                            # list all
-curl -s http://localhost:8321/api/skills/todo-digest                                # read one
-curl -s -X POST http://localhost:8321/api/skills \
-  -H 'Content-Type: application/json' \
-  -d '{"name": "todo-digest", "description": "Summarize today.md", "content": "# TODO Digest\n...", "allowedTools": ["Bash(curl *)", "Read"]}'
-curl -s -X PUT http://localhost:8321/api/skills/todo-digest \
-  -H 'Content-Type: application/json' -d '{"description": "New description"}'      # update
-curl -s -X DELETE http://localhost:8321/api/skills/todo-digest                      # delete
-```
-Always `GET /api/skills` before creating (check name collisions). **Omit frontmatter** from `content` — the API injects it.
+{{> ref:skills-crud }}

package/agent-assets/skills/external-services/SKILL.native.claude.md

@@ -1,9 +1,8 @@
 ---
 name: external-services
-description: Load when an external-services surface is in scope (Google Calendar / Obsidian / GitHub / Skills CRUD / scheduling) and Google Calendar is in native mode bound to Claude (`nativeBackend === "claude"`). Calendar runs through Claude's hosted Calendar connector directly; the daemon does not proxy Calendar. Other surfaces (Apple/Outlook Calendar, Obsidian, GitHub, scheduling, Skills CRUD) keep their direct routes.
+description: Load when an external-services surface is in scope and Google Calendar is in native mode bound to Claude (`nativeBackend === "claude"`). Calendar runs via Claude's hosted Calendar connector; daemon does not proxy. Obsidian, GitHub, scheduling, Skills CRUD keep direct routes.
 allowed-tools:
   - Bash(curl *)
-  - Bash(jq *)
   - Read
 ---
 

package/agent-assets/skills/external-services/SKILL.native.codex.md

@@ -1,9 +1,8 @@
 ---
 name: external-services
-description: Load when an external-services surface is in scope (Google Calendar / Obsidian / GitHub / Skills CRUD / scheduling) and Google Calendar is in native mode bound to Codex (`nativeBackend === "codex"`). Calendar runs through the in-session Calendar connector your Codex harness exposes directly; the daemon does not proxy Calendar. Other surfaces (Apple/Outlook Calendar, Obsidian, GitHub, scheduling, Skills CRUD) keep their direct routes.
+description: Load when an external-services surface is in scope and Google Calendar is in native mode bound to Codex (`nativeBackend === "codex"`). Calendar runs via the Codex Calendar connector; daemon does not proxy. Obsidian, GitHub, scheduling, Skills CRUD keep direct routes.
 allowed-tools:
   - Bash(curl *)
-  - Bash(jq *)
   - Read
 ---
 

package/agent-assets/skills/external-services/SKILL.native.gemini.md

@@ -1,9 +1,8 @@
 ---
 name: external-services
-description: Load when an external-services surface is in scope (Google Calendar / Obsidian / GitHub / Skills CRUD / scheduling) and Google Calendar is in native mode bound to Gemini (`nativeBackend === "gemini"`). Calendar runs through the in-session Calendar connector your Gemini harness exposes directly; the daemon does not proxy Calendar. Other surfaces (Apple/Outlook Calendar, Obsidian, GitHub, scheduling, Skills CRUD) keep their direct routes.
+description: Load when an external-services surface is in scope and Google Calendar is in native mode bound to Gemini (`nativeBackend === "gemini"`). Calendar runs via the Gemini Calendar connector; daemon does not proxy. Obsidian, GitHub, scheduling, Skills CRUD keep direct routes.
 allowed-tools:
   - Bash(curl *)
-  - Bash(jq *)
   - Read
 ---
 

package/agent-assets/skills/external-services/references/calendar-apple.md

@@ -0,0 +1,97 @@
+---
+kind: reference
+name: calendar-apple
+description: Apple Calendar (iCloud CalDAV) reference — list/get/create/update/delete with recurring-instance gotchas, app-specific-password setup probe, no proactive notifications. Stripped when `apple_calendar` is not configured.
+---
+
+<!-- service:apple-calendar -->
+## Apple Calendar (iCloud CalDAV)
+
+Use this section **only when `rules/management.md` Schedule = Apple Calendar**. The provider-routing table at the top of this skill is non-negotiable.
+
+The route shape mirrors `/api/calendar/*` so prose patterns transfer: list → get → patch / create / delete. Differences are flagged below.
+
+### Probe configuration before first use
+```bash
+curl -s http://localhost:8321/api/apple-calendar/status
+# → { "configured": bool, "available": bool }
+```
+- `configured: false` → user has not entered Apple ID + app-specific password yet. Tell the user to open the dashboard's Apple Calendar card (Connections page) and paste a password from `appleid.apple.com` → Sign-In and Security → App-Specific Passwords. **Do not try to read or write events** until `available: true`.
+- `configured: true, available: false` → credentials are stored but iCloud rejected the last connection. Surface verbatim; common cause is the user revoked the app-specific password.
+
+### List events
+```bash
+curl -s "http://localhost:8321/api/apple-calendar/events?date=today&days=3"
+```
+Same query params as Google: `date` (`YYYY-MM-DD` or `today`), `days` (max 90). Returns `{ events: [...] }` with the same JSON shape used by the Google route — `id`, `summary`, `start`, `end`, `location`, `description`, `allDay`, `status`, plus two Apple-specific fields:
+- `recurring` (bool) — true for any event in a recurring series.
+- `recurrenceId` (string|null) — populated for an expanded instance of a series.
+
+For a recurring instance the `id` is `<UID>__<RECURRENCE-ID>` so you can address a specific occurrence.
+
+**Timezones**: dateTime values are emitted in UTC (`Z` suffix). Convert to the user's local timezone before showing them.
+
+### Get event detail
+```bash
+curl -s "http://localhost:8321/api/apple-calendar/events/<id>"
+```
+Always GET before PATCH so you see the current summary/start/end.
+
+### Create event (write — Autonomous)
+```bash
+curl -s -X POST http://localhost:8321/api/apple-calendar/events \
+  -H 'Content-Type: application/json' \
+  -d '{"summary": "Team meeting", "start": "2026-04-26T14:00:00+09:00", "end": "2026-04-26T15:00:00+09:00"}'
+```
+Optional: `description`, `location`. **[Apple only]** `attendees`, `reminders`, `recurrence`, `visibility` from the Google shape are accepted by the Zod schema but are silently dropped — iCloud invitations and reminder defaults belong to the user's Apple ID and the agent should not author them. If a user asks for those, tell them and stop.
+
+### Update event (write — Autonomous)
+```bash
+curl -s -X PATCH http://localhost:8321/api/apple-calendar/events/<id> \
+  -H 'Content-Type: application/json' \
+  -d '{"start": "2026-04-26T15:00:00+09:00", "end": "2026-04-26T16:00:00+09:00"}'
+```
+
+**[Apple only] Recurring-event editing semantics — read before writing**
+- A composite id (one whose suffix matches `__YYYY-MM-DD…`) addresses **one occurrence** of a series. PATCH/DELETE on it returns `501 recurring_instance_unsupported`. To move a single occurrence the user must edit it from Calendar.app.
+- A bare id whose GET returned `recurring: true` is the **series master**. PATCH on the master shifts the **entire series** (every future occurrence moves), and DELETE removes the entire series. Confirm with the user that they intend a series-level edit before issuing the call — agents have historically read "PATCH this event's start" as a single-instance reschedule, which is wrong here.
+- A bare id with `recurring: false` is a normal one-off event — PATCH/DELETE behave as usual.
+- `summary`, `start`, and `end` may be updated independently. Toggling all-day-ness (`YYYY-MM-DD` ↔ `…T…Z`) requires providing **both** `start` and `end` in the same PATCH; the codec rejects partial all-day toggles with `400 validation_error`.
+- Time strings must include a TZ offset (`Z` or `±HH:MM`); naked ISO without offset returns `400 validation_error` — do not interpret a user-stated time as local without an explicit offset.
+
+### Delete event (write — Autonomous)
+```bash
+curl -s -X DELETE http://localhost:8321/api/apple-calendar/events/<id>
+```
+Same recurring semantics as PATCH (see the rules block above).
+
+### List calendars
+```bash
+curl -s http://localhost:8321/api/apple-calendar/calendars
+# → { "calendars": [{ id, summary, description, primary }, ...] }
+```
+The `id` is an opaque CalDAV URL. The user's primary calendar is marked `primary: true`. To change which calendar create/list reads, see the dashboard Apple Calendar card.
+
+### Free/busy query
+```bash
+curl -s -X POST http://localhost:8321/api/apple-calendar/freebusy \
+  -H 'Content-Type: application/json' \
+  -d '{"timeMin": "2026-04-26T09:00:00Z", "timeMax": "2026-04-26T18:00:00Z"}'
+```
+**[Apple only]** Free-busy is derived from `listEvents` — events with `status: "cancelled"` are excluded. `calendarIds` is ignored (the primary calendar is the only target).
+
+### Apple Calendar error envelope
+
+| HTTP | `error` | What it means / what to do |
+|---|---|---|
+| 400 | `validation_error` | Bad request shape. Fix and retry. |
+| 401 | `auth_failed` | iCloud rejected the credentials. Tell the user to refresh the app-specific password in the dashboard. |
+| 404 | `not_found` | Event id unknown or already deleted. Re-list before retrying. |
+| 501 | `recurring_instance_unsupported` | The id targets a single occurrence of a recurring series — see the PATCH/DELETE notes above. |
+| 502 | `apple_calendar_error` | Upstream iCloud / CalDAV error. `message` carries the wire text. |
+| 503 | `apple_calendar_not_configured` | Credentials missing or last connection failed. Run the status probe above. |
+
+### Known gap: no proactive notifications
+
+The hourly polling pivot (`schedule.approaching` events, observation deltas) only fires for Google Calendar today. With Apple Calendar selected, on-demand DM queries work but the agent will not proactively warn about an imminent event — the user's own iOS / macOS Calendar.app notifications fill that gap.
+<!-- /service:apple-calendar -->

package/agent-assets/skills/external-services/references/calendar-google.md

@@ -0,0 +1,72 @@
+---
+kind: reference
+name: calendar-google
+description: Google Calendar direct-mode reference — list/get/create/update/delete events, list calendars, free-busy. ATTENDEES PATCH replaces the whole list. Stripped by the integration-mode filter when `google_calendar !== "direct"`.
+---
+
+<!-- service:calendar -->
+## Calendar
+
+Google Calendar proxy. Operates on the user's primary calendar (configurable via `calendarId` param).
+
+**Timezone rule**: Always include a TZ offset in `start`/`end` dateTime values (e.g. `-04:00`). All-day events use `YYYY-MM-DD` (no TZ needed).
+
+**Event status**: GET returns deleted events with `status: "cancelled"` (200, not 404). Always check `status` before acting. The list endpoint automatically excludes cancelled events.
+
+### List events
+```bash
+curl -s "http://localhost:8321/api/calendar/events?date=today&days=3"
+```
+
+### Get event detail
+```bash
+curl -s "http://localhost:8321/api/calendar/events/abc123eventid"
+```
+**Always GET before PATCH** to see current state and attendees.
+
+### Create event (write — Autonomous)
+```bash
+curl -s -X POST "http://localhost:8321/api/calendar/events" \
+  -H 'Content-Type: application/json' \
+  -d '{"summary": "Team meeting", "start": "2026-04-02T14:00:00-04:00", "end": "2026-04-02T15:00:00-04:00"}'
+```
+Optional: `description`, `location`, `reminders`, `recurrence`, `attendees`, `visibility`. All-day: `YYYY-MM-DD`. Attendees: add `?sendUpdates=all` to notify. RRULE: `RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR`.
+
+### Update event (write — Autonomous; commonly on the starter denylist)
+```bash
+curl -s -X PATCH "http://localhost:8321/api/calendar/events/abc123" \
+  -H 'Content-Type: application/json' \
+  -d '{"start": "2026-04-02T15:00:00-04:00", "end": "2026-04-02T16:00:00-04:00"}'
+```
+For recurring events, use the instance ID to update a single occurrence — never PATCH the master.
+
+**ATTENDEES WARNING**: PATCH with `attendees` **replaces the entire list** — it does NOT append. To add one attendee: (1) GET, (2) copy existing, (3) add new, (4) PATCH full list.
+
+### Delete event (write — Autonomous; default starter denylist denies it)
+```bash
+curl -s -X DELETE "http://localhost:8321/api/calendar/events/abc123"
+```
+Add `?sendUpdates=all` to notify attendees. Do NOT PATCH a cancelled event.
+
+### List calendars
+```bash
+curl -s http://localhost:8321/api/calendar/calendars
+```
+
+### Free/busy query
+```bash
+curl -s -X POST http://localhost:8321/api/calendar/freebusy \
+  -H 'Content-Type: application/json' \
+  -d '{"timeMin": "2026-04-11T09:00:00-04:00", "timeMax": "2026-04-11T18:00:00-04:00"}'
+```
+
+### Calendar error envelope (direct mode)
+
+| HTTP | `error` | What it means / what to do |
+|---|---|---|
+| 400 | `validation_error` | Bad request shape (e.g. missing `start`/`end`, malformed RRULE). Fix and retry. |
+| 404 | `not_found` | Event id unknown or already deleted. Re-list before retrying. |
+| 410 | `integration_delegated` | Calendar flipped to delegated mode mid-session. This skill body is direct-only — re-read `integrations.md` and use `POST /api/integrations/google_calendar/exec` (cross-backend task mode) or your session backend's native Calendar MCP (the same-backend variant) instead. |
+| 502 | `calendar_error` | Upstream Google API error — `message` carries the API's text. Surface verbatim; do not retry unless clearly transient. |
+| 503 | `calendar_not_configured` | Direct OAuth credentials are missing or the user has disabled Calendar in settings. Tell the user and stop. |
+<!-- /service:calendar -->

package/agent-assets/skills/external-services/references/calendar-outlook.md

@@ -0,0 +1,36 @@
+---
+kind: reference
+name: calendar-outlook
+description: Outlook Calendar reference (Microsoft Graph) — read-only on-demand. Same query shape as Google. Stripped when `outlook_calendar` is not configured.
+---
+
+<!-- service:outlook-calendar -->
+## Outlook Calendar (Microsoft Graph)
+
+Use this section **only when `rules/management.md` Schedule = Outlook Calendar**. The provider-routing table at the top of this skill is non-negotiable.
+
+v1 is **read-only and on-demand** — there is no Outlook calendar poller, so `schedule.approaching` events do not fire for Outlook calendars (the user's own Outlook clients fill that gap). Write surfaces (create / update / delete) are deferred. If the user asks the agent to schedule or change an Outlook event, tell them you can read the calendar but must defer the write to them.
+
+OAuth is **shared with Outlook Mail** via the same MSAL cache row (`mail:outlook:<accountId>`) — if Outlook Mail is configured `direct` and authenticated, calendar reads succeed with no second consent.
+
+### List events
+```bash
+curl -s "http://localhost:8321/api/calendar/outlook/events?date=today&days=3"
+```
+Same query params as Google (`date`: `YYYY-MM-DD` or `today`; `days`: 1–90; optional `calendarId`). Returns `{ events: [...], accountId }`.
+
+### List calendars
+```bash
+curl -s http://localhost:8321/api/calendar/outlook/calendars
+```
+Returns `{ calendars: [...], accountId }`. The user's primary calendar is marked `primary: true`.
+
+### Outlook Calendar error envelope
+
+| HTTP | `error` | What it means / what to do |
+|---|---|---|
+| 400 | bad query | Malformed `date` or `days` value. |
+| 502 | `calendar_error` | Upstream Microsoft Graph error — `message` carries wire text. |
+| 503 | `outlook_not_configured` | No authenticated Outlook account. Direct OAuth credentials missing. |
+| 503 | `outlook_calendar_disabled` | The user toggled Outlook Calendar off in Settings → Calendar. Tell the user and stop. |
+<!-- /service:outlook-calendar -->

package/agent-assets/skills/external-services/references/github.md

@@ -0,0 +1,17 @@
+---
+kind: reference
+name: github
+description: GitHub direct-mode reference — list repos, list PRs, comment on a PR. Autonomous tier. Stripped when `github` is not configured.
+---
+
+<!-- service:github -->
+## GitHub
+
+```bash
+curl -s http://localhost:8321/api/github/repos                              # list watched repos
+curl -s "http://localhost:8321/api/github/pulls?owner=user&repo=repo&state=open" # list PRs
+curl -s -X POST http://localhost:8321/api/github/pulls/comment \
+  -H 'Content-Type: application/json' \
+  -d '{"owner": "user", "repo": "repo", "pull_number": 42, "comment": "LGTM"}' # comment — Autonomous
+```
+<!-- /service:github -->

package/agent-assets/skills/external-services/references/obsidian.md

@@ -0,0 +1,49 @@
+---
+kind: reference
+name: obsidian
+description: External Obsidian vault CRUD — separate from the agent's primary management vault. Routed via /api/obsidian/*. Stripped when `obsidian` is not configured.
+---
+
+<!-- service:obsidian -->
+## Obsidian (external vault)
+
+**Scope**: this skill targets a **separate** Obsidian vault the user maintains
+alongside this app — e.g. a personal knowledge base. It is **not** the agent's
+own primary management store. The agent's primary files (`today.md`,
+`roadmap.md`, `projects/`, `rules/`, `routines/`, `user/`, `agent/`, …) live
+in the primary vault and are reached via `/api/context/*` (see the `context`
+skill). **Never** use this skill to read or write the primary vault.
+
+Use this skill when the user asks the agent to look up, append to, or create
+notes inside their external knowledge vault — never for the agent's own
+working state.
+
+Output language: external-vault writes are Policy C — see `<output_language_policy>`. Preserve verbatim any path / file-name patterns the user has established.
+
+Full CRUD over the external vault. Requires the Obsidian app running (the
+CLI proxies through it). Omit `.md` extension from paths. All writes are
+Autonomous; the daemon does not DM the owner before/after the call. Call
+`POST /api/notify` yourself when the user would want to know.
+
+```bash
+curl -s http://localhost:8321/api/obsidian/status                            # external vault availability
+curl -s "http://localhost:8321/api/obsidian/search?q=meeting+notes&limit=10" # search external vault
+curl -s http://localhost:8321/api/obsidian/notes/Daily%20Notes/2026-04-06    # read external note
+curl -s -X POST http://localhost:8321/api/obsidian/notes \
+  -H 'Content-Type: application/json' \
+  -d '{"name": "Meeting Notes 2026-04-02", "content": "# Meeting\n..."}'    # create external note (fails if exists)
+curl -s -X PUT http://localhost:8321/api/obsidian/notes/Projects/ProjectA \
+  -H 'Content-Type: application/json' -d '{"content": "# Full body"}'       # create-or-overwrite external note
+curl -s -X PATCH http://localhost:8321/api/obsidian/notes \
+  -H 'Content-Type: application/json' \
+  -d '{"file": "Meeting Notes 2026-04-02", "content": "\n- Action item"}'   # append to external note
+curl -s -X PATCH http://localhost:8321/api/obsidian/daily \
+  -H 'Content-Type: application/json' -d '{"content": "- [ ] Follow up"}'   # append to external daily note
+curl -s -X DELETE http://localhost:8321/api/obsidian/notes/Projects/Old      # delete from external vault (moves to trash)
+```
+**Endpoint choice**: Read → GET, Create-only → POST, Edit → PUT, Append → PATCH.
+
+If the user's request is really about the agent's own state (today, roadmap,
+projects, journal, rules, routines, user profile), switch to the `context`
+skill and the `/api/context/*` endpoints instead.
+<!-- /service:obsidian -->

package/agent-assets/skills/external-services/references/skills-crud.md

@@ -0,0 +1,27 @@
+---
+kind: reference
+name: skills-crud
+description: Dashboard-shaped CRUD for user-authored skills under ~/.personal-agent/skills/. Built-in skills are read-only (403).
+---
+
+## Skills Management
+
+User-authored skills: `~/.personal-agent/skills/{slug}/SKILL.md`. Built-in skills are read-only (403). Slug: lowercase kebab-case `[a-z0-9][a-z0-9-]*`, 1–64 chars.
+
+```bash
+curl -s http://localhost:8321/api/skills                                            # list all
+curl -s http://localhost:8321/api/skills/todo-digest                                # read one
+curl -s -X POST http://localhost:8321/api/skills \
+  -H 'Content-Type: application/json' \
+  -d '{"name": "todo-digest", "description": "Summarize today.md", "content": "# TODO Digest\n...", "allowedTools": ["Bash(curl *)", "Read"]}'
+curl -s -X PUT http://localhost:8321/api/skills/todo-digest \
+  -H 'Content-Type: application/json' -d '{"description": "New description"}'      # update
+curl -s -X DELETE http://localhost:8321/api/skills/todo-digest                      # delete
+```
+Always `GET /api/skills` before creating (check name collisions). **Omit frontmatter** from `content` — the API injects it.
+
+The description is the **only** routing signal the SDK uses to pick a
+skill — keep it under 280 chars and make the trigger surface
+distinct from every other skill in the manifest. Slug grammar is
+strict: `[a-z0-9][a-z0-9-]*[a-z0-9]` or `[a-z0-9]` (single char),
+1-64 chars total. PUT rejects collisions with built-in slugs.