@aitne-sh/aitne 0.1.3 → 0.1.4

package/agent-assets/docs/troubleshooting/auth-failed.md

@@ -21,9 +21,10 @@ ask_examples:
   - How do I re-login to Claude?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-04
 related:
   - concepts/auth-health
+  - concepts/costs-and-quotas
   - features/operations/backend-routing
 ---
 
@@ -36,17 +37,35 @@ related:
 
 ## Most Likely Causes
 
-1. **Token expired** (Codex, Gemini API).
-2. **Claude credentials rotated** out of the keychain.
-3. **Scope changed** (e.g. Claude Max plan was downgraded).
+1. **Provider API key revoked or rotated** — the most common cause
+   on a healthy install. Re-paste the key on `/settings/models`.
+2. **Subscription-fallback login expired** when no API key was
+   registered (the daemon was running on the CLI's local login —
+   `claude`, `codex login`, `gemini auth` — and that session timed
+   out). The recommended fix is to register an API key.
+3. **Account-level scope change** at the provider (key disabled,
+   project deleted, billing suspended). For cloud providers
+   (Bedrock / Vertex / Foundry / Azure OpenAI / Gemini-Vertex),
+   IAM-role / service-account changes show up the same way.
 
 ## Diagnostic Steps
 
 1. Click the pill to see the recovery hint.
-2. For Claude: `claude` CLI login, the daemon picks up the new
-   credentials on probe refresh.
-3. For Codex / Gemini: paste a fresh token / API key on
-   `/settings/models`.
+2. Check `/settings/models` — the backend card shows whether it is
+   running on a registered API key (the supported path) or on the
+   subscription fallback. The `SubscriptionAuthWarning` banner
+   appears whenever any backend is on the fallback.
+3. If on the API key, paste a fresh key on `/settings/models` — the
+   daemon mirrors it into `process.env` and re-probes immediately.
+4. If on the subscription fallback, the recommended fix is to
+   register an API key on `/settings/models` (or one of the cloud-
+   provider options — see
+   [Use a Cloud Provider for Models](../guides/use-cloud-providers.md)).
+   If you cannot or do not want to, run the corresponding CLI login
+   (`claude`, `codex login`, `gemini auth`) and the daemon picks up
+   the new credentials on the next probe. Note that this fallback
+   is not provider-supported for automated agent use — see
+   [Costs and Quotas](../concepts/costs-and-quotas.md).
 
 ## Confirming the Fix
 

package/agent-assets/docs/troubleshooting/quota-exhausted.md

@@ -4,13 +4,14 @@ slug: troubleshooting/quota-exhausted
 title: Quota Exhausted
 id: quota-exhausted
 aliases:
-  - max5 limit hit
+  - api quota exceeded
+  - rate limit
   - opus window
-  - subscription limit
 category: troubleshooting
 summary: |
   A backend reported a quota error and the router fell over to the
-  fallback. Either wait for the window to refresh or upgrade the plan.
+  fallback. Wait for the provider window to refresh, raise your API
+  spending limit, or pin a different model.
 section: quota-exhausted
 tags:
   - troubleshooting
@@ -18,13 +19,15 @@ tags:
   - backends
 status: stable
 ask_examples:
-  - Why am I seeing "subscription limit reached"?
-  - When does the Opus window reset?
+  - Why did Aitne fall over to the fallback backend?
+  - Why is my Anthropic API call returning a quota error?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-04
 related:
   - concepts/costs-and-quotas
+  - concepts/auth-health
+  - guides/use-cloud-providers
 ---
 
 # Quota Exhausted
@@ -37,16 +40,36 @@ related:
 
 ## Most Likely Causes
 
-1. **5-hour Opus window** burned by a heavy routine cluster.
-2. **Daily Sonnet bucket** hit on a long-running session.
-3. **Gemini per-day cap** for `gemini-2.5-flash` reached on the free
-   tier.
+1. **Provider rate limit** on your API key (Anthropic / OpenAI /
+   Google) — the supported path. Check the provider console for the
+   per-minute / per-day caps tied to your billing.
+2. **Gemini per-day cap** for `gemini-2.5-flash` reached on the free
+   tier (`GEMINI_API_KEY` without billing).
+3. **Cloud-provider quota** — Bedrock / Vertex / Foundry / Azure
+   OpenAI / Gemini-Vertex enforce their own per-region / per-model
+   quotas. The error surfaces the same way as a direct-API quota.
+4. **Subscription fallback exhausted** — no API key registered, so
+   the backend is running on the CLI's local subscription login.
+   The underlying provider's subscription limits then apply (e.g.
+   Claude's rolling 5-hour Opus window on a Max plan login). The
+   recommended fix is to register an API key on `/settings/models`;
+   the fallback is not provider-supported for automated agent use.
+   See [Costs and Quotas](../concepts/costs-and-quotas.md).
 
 ## Diagnostic Steps
 
 1. Open `/analytics` and look at the by-backend rollup.
-2. The "next reset" timestamp on Claude's card tells you when the
-   rolling window refreshes.
+2. Check `/settings/models` to confirm whether the affected backend
+   is on a registered API key (the `SubscriptionAuthWarning` banner
+   is *absent*) or on the subscription fallback (banner *present*).
+3. If on an API key, open the provider console and verify your
+   account's spending / rate-limit settings. For cloud providers,
+   open the matching console (AWS / GCP / Azure) and check the
+   per-region / per-model quota.
+4. If on the subscription fallback, the backend card shows the
+   "next reset" timestamp for the rolling window. Consider
+   registering an API key — see
+   [Costs and Quotas](../concepts/costs-and-quotas.md).
 
 ## Confirming the Fix
 

package/agent-assets/skills/context/SKILL.md

@@ -8,6 +8,12 @@ allowed-tools:
 
 # Context File Update Guide
 
+Output language: follow `<output_language_policy>`. Context files are
+Policy B — H2/H3 headers from `agent-assets/templates/` are skeleton
+(English); body prose, bullets, and summaries are written in
+`<settings primary_language>`. Preserve user-customized headers
+verbatim (whichever language the user rewrote them in).
+
 Context files are the agent's working memory, stored in the **primary
 management vault**. All writes go through the Daemon API — never touch
 files on disk directly.

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

@@ -289,6 +289,10 @@ 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

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

@@ -0,0 +1,320 @@
+---
+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.
+allowed-tools:
+  - Bash(curl *)
+  - Bash(jq *)
+  - Read
+---
+
+# External Services — Native Mode (Claude Calendar connector)
+
+Base URL: `http://localhost:8321`. All daemon calls via `curl -s` with
+`Content-Type: application/json` on POST/PATCH/PUT.
+
+> **Refusal directive — read first.** Google Calendar is in `native`
+> mode bound to Claude. Do **NOT** call any of:
+>
+> - `POST /api/integrations/google_calendar/exec` (returns `410` with
+>   `X-Integration-Mode: native`)
+> - `POST /api/integrations/google_calendar/reconcile` (410)
+> - `/api/calendar/*` (route-prefix 410 in native mode)
+>
+> Reach Google Calendar through the
+> `mcp__claude_ai_Google_Calendar__*` MCP tools this Claude session
+> already holds.
+>
+> Only **Google Calendar** is integration-gated here. Apple Calendar,
+> Outlook Calendar, Obsidian, GitHub, recurring-schedule CRUD,
+> one-shot scheduling, and Skills CRUD remain direct-mode routes
+> regardless of Calendar's mode.
+
+To confirm the binding, read `<integration_modes>` (carries
+`google_calendar="native"`) and the `<integration-routing-table>` block
+in the session preamble.
+
+## Source of Truth (READ FIRST)
+
+The same two files documented in the direct-mode body are still
+authoritative for non-Calendar routing:
+
+1. **`rules/management.md` → `## Source of Truth`** — durable
+   user-authored answers ("Schedule = Google Calendar", "Tasks =
+   Notion", etc.).
+2. **`~/.personal-agent/integrations.md` → `## Note Sources`** — the
+   daemon-rendered snapshot for the user's external Obsidian vault path
+   plus Notion's mode.
+
+If `rules/management.md` Schedule = Apple Calendar or Outlook Calendar,
+the user's chosen provider is **not** Google Calendar and the
+native-Claude binding is irrelevant — route to `/api/apple-calendar/*`
+or `/api/calendar/outlook/*` exactly as the direct-mode body documents.
+The native gate covers Google Calendar only.
+
+## Shell rules (read before writing curl pipelines)
+
+- **JSON post-processing: use `jq`, never `python3`.** `python3` is not
+  in the daemon's allowlist; the security hook denies `... | python3`
+  pipelines under `permissionMode: "dontAsk"`. Use `jq` for filtering.
+- **`jq` is restricted**: `--slurpfile`, `--rawfile`, `-L`, and the
+  `env` filter are blocked. Use the filter language itself.
+- **`curl` is restricted to `http://localhost:8321`**: connection-
+  override flags (`--connect-to`, `--resolve`, `--config`, `--proxy`)
+  and non-localhost hosts are blocked.
+
+---
+
+<!-- service:calendar -->
+## Google Calendar — Claude connector (native MCP)
+
+Tool namespace: `mcp__claude_ai_Google_Calendar__`
+
+### Read-class tools (`requiredCapabilities` floor + optional reads)
+
+| Capability | Tool | Use |
+|---|---|---|
+| `list_events` | `mcp__claude_ai_Google_Calendar__list_events` | Window-list events on a calendar. |
+| `get_event` | `mcp__claude_ai_Google_Calendar__get_event` | Fetch a single event by id. |
+| `list_calendars` | `mcp__claude_ai_Google_Calendar__list_calendars` | Enumerate the user's calendars (find `primary`). |
+| `suggest_time` | `mcp__claude_ai_Google_Calendar__suggest_time` | Free-slot proposal — pure compute, no calendar side effect. |
+
+Canonical list call:
+
+```
+mcp__claude_ai_Google_Calendar__list_events(
+  calendarId="primary",
+  timeMin="<ISO-8601 with offset>",
+  timeMax="<ISO-8601 with offset>",
+  maxResults=50
+)
+```
+
+Canonical detail read (always GET-before-PATCH; see PATCH semantics
+below):
+
+```
+mcp__claude_ai_Google_Calendar__get_event(
+  calendarId="primary",
+  eventId="<id>"
+)
+```
+
+### Destructive tools (require explicit user confirmation)
+
+Per the registry's
+`google_calendar.backendConnectors.claude.destructiveTools`:
+
+- `create_event` — adds a new event.
+- `update_event` — mutates an existing event (attendees field is
+  whole-list replacement; see warning below).
+- `delete_event` — removes the event.
+- `respond_to_event` — dispatches an RSVP to the organizer.
+
+Apply the destructive-confirm contract every time. Summarise the
+intended change ("create 30-min focus block at 14:00 JST tomorrow"),
+wait for explicit OK, then issue the call.
+
+**ATTENDEES WARNING.** `update_event` replaces the attendees array
+verbatim — it does not append. To add one attendee:
+
+1. `get_event(...)` → copy `attendees: [...]`.
+2. Append the new attendee object.
+3. `update_event(... attendees=[<full list>])`.
+
+Forgetting the GET drops every existing invitee.
+
+**Recurring events.** Single-instance edits require the instance id
+(usually returned alongside the master in `list_events`). PATCHing the
+master id shifts the whole series. Confirm with the user which scope
+they meant — "move this 9am to 10am" can mean the master or a single
+occurrence and the agent must not guess.
+
+`suggest_time` is read-only and exempt from the confirm dance.
+
+### Time discipline
+
+- Timed events use ISO 8601 timestamps with a TZ offset
+  (`2026-04-26T14:00:00+09:00`). Naked ISO without offset is rejected
+  by the connector.
+- All-day events use `YYYY-MM-DD` with no offset.
+- Be explicit which shape the destructive-confirm plan describes.
+
+### Imminent-event reminders (hourly_check)
+
+Native mode replaces the daemon-side
+`POST /api/integrations/google_calendar/reconcile` POST that delegated
+mode uses. In native mode, the agent itself drives the imminent-window
+fetch every hour and POSTs each materialised event to
+`/api/observations`. The hourly_check native variant's Step 0b spells
+out the exact shape; this skill describes the call surface.
+
+Free-busy queries are composed locally — `suggest_time` returns slot
+proposals against a primary calendar; for explicit free-busy across
+multiple calendars, list each calendar's events in the window and
+intersect.
+
+<!-- /service:calendar -->
+
+---
+
+<!-- service:apple-calendar -->
+## Apple Calendar (iCloud CalDAV) — direct, unchanged
+
+If `rules/management.md` Schedule = Apple Calendar, use the
+`/api/apple-calendar/*` routes documented in the base body. Apple
+Calendar has no MCP connector; native-mode gating does not apply.
+
+The direct-mode body's full apple-calendar reference (status probe,
+list/get/create/update/delete, recurring-event semantics, error
+envelope) is the source of truth — copy that section's shape
+verbatim. The note here exists only to remind the agent that the
+native binding above is Google-only.
+<!-- /service:apple-calendar -->
+
+---
+
+<!-- service:outlook-calendar -->
+## Outlook Calendar (Microsoft Graph) — direct, unchanged
+
+If `rules/management.md` Schedule = Outlook Calendar, use
+`/api/calendar/outlook/*` per the direct-mode body. Microsoft does not
+ship a hosted Outlook Calendar connector for Claude / Codex / Gemini
+today; native-mode gating does not apply.
+<!-- /service:outlook-calendar -->
+
+---
+
+<!-- service:obsidian -->
+## Obsidian (external vault) — direct, unchanged
+
+**Scope**: this skill targets the **separate** Obsidian vault the user
+maintains alongside this app — never the agent's primary management
+store (`today.md`, `roadmap.md`, `projects/`, `rules/`, `routines/`,
+`user/`, `agent/`). Those are reached via `/api/context/*` (see the
+`context` skill).
+
+Full CRUD over the external vault. Requires the Obsidian app running
+(the CLI proxies through it). Omit the `.md` extension from paths.
+All writes are Autonomous; the daemon does not DM the owner before /
+after the call.
+
+```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 (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
+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
+curl -s -X PATCH http://localhost:8321/api/obsidian/daily \
+  -H 'Content-Type: application/json' -d '{"content": "- [ ] Follow up"}'   # append to external daily
+curl -s -X DELETE http://localhost:8321/api/obsidian/notes/Projects/Old      # delete (moves to trash)
+```
+
+**Endpoint choice**: Read → GET, Create-only → POST, Edit → PUT,
+Append → PATCH.
+<!-- /service:obsidian -->
+
+---
+
+<!-- service:github -->
+## GitHub — direct, unchanged
+
+```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 -->
+
+---
+
+<!-- service:notion -->
+## Notion
+
+Notion operations live in the dedicated `notion` skill — load that
+when the user asks anything Notion-shaped (search, query, read,
+create, update, archive). Notion's own native binding is independent
+of Calendar's; the `notion` skill picks the right variant from the
+session's integration state.
+<!-- /service:notion -->
+
+---
+
+## Persisting Calendar observations from native fetches
+
+When the hourly_check native flow's Step 0b fetches imminent-window
+events, POST each materialised event to `/api/observations` so
+subsequent runs can dedup. The daemon computes `contentHash`
+server-side via `@personal-agent/shared/observations-hash.ts` — pass
+the raw `payload`:
+
+```bash
+curl -s -X POST http://localhost:8321/api/observations \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "source": "google_calendar",
+    "type": "calendar:lifecycle",
+    "ref": "<eventId>",
+    "actor": "user",
+    "receivedAt": "<ISO-8601 UTC>",
+    "summary_text": "<title — start..end>",
+    "refs": {
+      "eventId": "<id>",
+      "calendarId": "primary",
+      "windowKey": "primary:imminent"
+    },
+    "payload": <verbatim MCP event object>
+  }'
+```
+
+`/api/observations` is never gated. HTTP 409 indicates a mode-flip race
+window (§11.3.1) — stop and re-read `<integration_modes>`.
+
+The two-fetch pattern (imminent 15-min + 24-hour drift detection)
+documented in `routine.hourly_check.native.claude.md` is the canonical
+shape; this skill describes the per-call surface, not the orchestration.
+
+---
+
+## Scheduling — direct, unchanged
+
+One-shot wake-ups, pre-composed DMs, and recurring agent tasks live in
+the `schedule` skill — `/api/schedule`, `/api/schedule/dm`,
+`/api/recurring-schedules`. Native-mode gating does not apply to the
+schedule surface (scheduling is daemon-internal, not an integration).
+
+---
+
+## Skills Management — direct, unchanged
+
+User-authored skills: `~/.personal-agent/skills/{slug}/SKILL.md`.
+Built-in skills are read-only (403). Native-mode gating does not apply.
+
+```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.
+
+## Cost / audit
+
+Native Calendar MCP calls land `agent_actions` rows of type
+`mcp_call` with `provider="claude"`, the tool name, and the parent
+`event_id` / `processKey`. The cost dashboard joins these to the
+registry by `toolNamespace` prefix for the `nativeAttribution` rollup
+(§14.4).