@aitne-sh/aitne 0.1.0

package/agent-assets/skills/project-doc/seeds/project-shape.seed.json

@@ -0,0 +1,25 @@
+{
+  "kind": "knowledge_layout",
+  "files": [
+    {
+      "path": "projects/*.md",
+      "purpose": "Per-project context document for Git-backed projects",
+      "sections": [
+        { "heading": "## Overview", "contains": "one-paragraph description of the project and its current state" },
+        { "heading": "## Git Activity", "contains": "recent commits, branches, contributors summarised by the daemon" },
+        { "heading": "## Lifecycle Phases", "contains": "phase markers (planning, build, ship, maintenance)" },
+        { "heading": "## Notable Changes", "contains": "human-readable notes on important commits or decisions" },
+        { "heading": "## Open Threads", "contains": "follow-ups and pending questions tracked across sessions" },
+        { "heading": "## History (compressed)", "contains": "older content rolled up to keep the active body concise" }
+      ]
+    },
+    {
+      "path": "git-repos/*.md",
+      "purpose": "Per-repository context for non-project watched repositories",
+      "sections": [
+        { "heading": "## Activity", "contains": "summarised recent activity for the watched repo" },
+        { "heading": "## Recent Pushes", "contains": "list of push events with dates and short summaries" }
+      ]
+    }
+  ]
+}

package/agent-assets/skills/project-doc/seeds/slug-grammar.seed.json

@@ -0,0 +1,20 @@
+{
+  "kind": "convention_notes",
+  "notes": [
+    {
+      "topic": "Slug format",
+      "rule": "Project and repo slugs are kebab-case, lowercase letters with hyphens between words.",
+      "example": "projects/cost-explorer.md, git-repos/personal-agent.md"
+    },
+    {
+      "topic": "Slug length",
+      "rule": "Slugs are 32 characters or fewer, including the hyphens but excluding the .md suffix.",
+      "example": "projects/personal-agent-skills.md is at the upper bound"
+    },
+    {
+      "topic": "Reserved stems",
+      "rule": "Stems _index and _archive are reserved for daemon-maintained files and not in use as project slugs.",
+      "example": "projects/_index.md is a directory listing, not a project file"
+    }
+  ]
+}

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

@@ -0,0 +1,198 @@
+---
+name: reading
+description: Load when the user mentions a book or highlight, weekly/monthly reviews need reading progress, or routines need to refresh the reading-taste profile (`user/reading-taste.md`) and propose new book candidates. Owns the taste-profile schema and recommendation rules.
+allowed-tools:
+  - Bash(curl *)
+  - Read
+---
+
+# Reading & Highlights Tracker
+
+The daemon stores books and reading highlights imported from Kindle
+(My Clippings.txt and the "Export Notebook" email pipeline) and manual
+entries. Data lives in `books` and `reading_highlights` tables. All
+display text in `reading-taste.md` must be English (project convention).
+
+## When to Use
+
+- **Monthly review**: generate reading report with books completed,
+  highlight counts, and reading pace.
+- **Weekly review** (Phase 5, routine.weekly_review.md): refresh the
+  reading-taste profile and propose book recommendations.
+- **User asks about a book**: query highlights and notes.
+- **User asks about reading history**: list books by status.
+- **Morning routine**: mention currently reading books (if user has active books).
+
+## Workflow
+
+1. Fetch books list with status and highlight counts.
+2. For specific book queries, fetch highlights.
+3. For reports, use the summary endpoint.
+
+## Roadmap candidate signal
+
+When a book / article request is **goal-shaped**, queue a
+`roadmap_candidate:reading` observation so the next roadmap refresh can
+land it in `## Long-term Plans` or `## Agent Action Plan`.
+
+Goal-shaped means the user expresses both a reading/learning objective
+and a future horizon or commitment. Examples:
+- "I want to read Designing Data-Intensive Applications before Q3."
+- "Learn Rust from this list this summer."
+- "Finish the ML papers before the September course starts."
+
+Do **not** queue a roadmap candidate for taste, preference, or finished
+reading notes without a future objective:
+- "I enjoyed Deep Work."
+- "Recommend me books like this."
+- "Add this article to my reading list" with no deadline or horizon.
+
+Record the signal with a stable reading-list/book/article ref:
+
+```bash
+curl -s -X POST http://localhost:8321/api/observations \
+  -H 'Content-Type: application/json' \
+  -d '{"source":"roadmap_candidate:reading","ref":"reading-goal-ddia-2026-q3","changeType":"created","actor":"agent","payload":{"kind":"reading_goal","horizon_tag":"2026-Q3","intent":"Finish Designing Data-Intensive Applications"}}'
+```
+
+Payload contract:
+- `kind`: `"reading_goal"`
+- `horizon_tag`: roadmap horizon tag (`YYYY-MM`, `YYYY-Qn`,
+  `YYYY spring|summer|autumn|winter`, or `undated` when the user gave
+  no date but clearly stated a future learning goal)
+- `intent`: concise human-readable goal, suitable for a Long-term Plan
+  line with `Source: reading`
+
+---
+
+## API Reference
+
+Base URL: `http://localhost:8321`
+
+### GET /api/books
+
+List books with optional filters.
+
+```bash
+# Currently reading
+curl -s "http://localhost:8321/api/books?status=reading"
+
+# All completed books (first page)
+curl -s "http://localhost:8321/api/books?status=completed&limit=50"
+
+# Walk past the 200-row cap via offset
+curl -s "http://localhost:8321/api/books?limit=200&offset=200"
+```
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `status` | string | all | reading, completed, abandoned, all |
+| `source` | string | all | kindle, audible, manual, all |
+| `limit` | number | 50 | Page size (1–200) |
+| `offset` | number | 0 | Rows to skip. Use with `limit` to paginate beyond the 200 cap |
+
+Response:
+```json
+{
+  "books": [
+    {
+      "id": 1,
+      "title": "Thinking, Fast and Slow",
+      "author": "Daniel Kahneman",
+      "source": "kindle",
+      "status": "reading",
+      "startedAt": null,
+      "completedAt": null,
+      "rating": null,
+      "notes": null,
+      "highlightCount": 47,
+      "createdAt": "2026-04-01T10:00:00Z"
+    }
+  ],
+  "total": 1,
+  "limit": 50,
+  "offset": 0,
+  "hasMore": false
+}
+```
+
+When iterating the entire library, keep calling with `offset += limit`
+until `hasMore === false`.
+
+### GET /api/books/:id/highlights
+
+Get highlights for a specific book.
+
+```bash
+curl -s "http://localhost:8321/api/books/1/highlights?limit=50"
+```
+
+### GET /api/books/summary
+
+Reading statistics.
+
+```bash
+curl -s "http://localhost:8321/api/books/summary?months=12"
+```
+
+Response:
+```json
+{
+  "byStatus": [
+    { "status": "reading", "count": 3 },
+    { "status": "completed", "count": 12 }
+  ],
+  "monthlyCompleted": [
+    { "month": "2026-04", "count": 1 },
+    { "month": "2026-03", "count": 2 }
+  ],
+  "totalHighlights": 234
+}
+```
+
+### PATCH /api/books/:id
+
+Update book status, rating, or notes.
+
+```bash
+curl -s -X PATCH "http://localhost:8321/api/books/1" \
+  -H "Content-Type: application/json" \
+  -d '{"status": "completed", "rating": 4}'
+```
+
+### POST /api/books/import-clippings
+
+Import Kindle My Clippings.txt.
+
+```bash
+curl -s -X POST "http://localhost:8321/api/books/import-clippings" \
+  -H "Content-Type: application/json" \
+  -d "{\"data\": \"$(cat 'My Clippings.txt')\"}"
+```
+
+---
+
+## Formatting Guide
+
+### Monthly review
+
+```
+## Reading Report (April 2026)
+Books completed: 2
+Currently reading: 3
+New highlights: 34
+
+### Completed This Month
+1. "Deep Work" by Cal Newport — ★★★★★
+2. "Atomic Habits" by James Clear — ★★★★
+
+### Currently Reading
+- "Thinking, Fast and Slow" by Daniel Kahneman (47 highlights)
+- "The Design of Everyday Things" by Don Norman (12 highlights)
+```
+
+---
+
+## Reading Taste Profile (`user/reading-taste.md`)
+
+{{> ref:reading-taste }}

package/agent-assets/skills/reading/references/reading-taste.md

@@ -0,0 +1,197 @@
+---
+kind: reference
+parent_skill: reading
+---
+
+This file captures what the user reads and *why* — topics they return to,
+how they think, values that keep surfacing in their highlights, and a
+rolling list of candidate books. It is dictionary-like (same layer as
+other `user/*.md` files) and is consumed on-demand — never injected
+into every session. Do not notify the user about taste updates.
+
+### When to refresh
+
+- **Weekly review, Phase 5**: required sweep (see task flow).
+- **On-demand**: if the user asks "what do my highlights say about me?"
+  or "recommend a book based on what I've read".
+- **After a book is marked `completed`** with rating ≥ 4: one-shot refresh
+  biased to that book's highlights.
+
+**Do not refresh** if fewer than 10 new highlights have accrued since the
+last sweep. A low-signal pass produces noise — prefer silence.
+
+### Refresh-trigger check (how to compute the delta reliably)
+
+The file carries a dedicated frontmatter line `Highlights at last sweep: N`
+holding the `totalHighlights` value from `GET /api/books/summary` at the
+time of the last successful write. To decide whether to refresh:
+
+1. `GET /api/context/user/reading-taste` — if 404, treat as
+   `N = 0` and proceed (first sweep).
+2. `GET /api/books/summary` — read `totalHighlights` as `M`.
+3. If `M - N < 10`, skip the sweep (log one bullet under agent-journal
+   "What worked": `reading sweep skipped — only (M-N) new highlights`).
+4. Otherwise, run the workflow. The new `M` becomes the `Highlights at
+   last sweep` value written on this sweep.
+
+Do **not** compare the `Sampled: X highlights` line — `X` is the
+sample size the agent read, not a count of highlights in the DB.
+
+### Sampling strategy
+
+You are working with potentially hundreds of highlights. Do not read them
+all. Use this sampling recipe:
+
+1. `GET /api/books?status=reading&limit=20` and
+   `GET /api/books?status=completed&limit=20` (most recently touched first).
+2. Pick up to 8 books: all currently-reading, plus the most recent
+   completed books to fill the slot.
+3. For each book: `GET /api/books/:id/highlights?limit=12`. The endpoint
+   sorts by `highlighted_at DESC` — for Kindle imports this is **when the
+   user highlighted on device**, not when the daemon ingested the email.
+   That means the 12-entry sample is representative of what the user
+   latched onto in a book, NOT a freshness-ordered activity feed. Treat
+   it as a broad taste sample, not a "last week" view.
+4. When sampling a book with >50 highlights total, you are viewing a
+   dozen out of many. Note this in the "Sampled" line of the file —
+   don't claim exhaustive coverage of a 200-highlight book.
+
+The refresh-trigger check (previous section) uses `totalHighlights` from
+`/api/books/summary` and is insensitive to `highlighted_at`; it detects
+"new highlights exist in the DB" regardless of their on-device date.
+
+### Required file schema
+
+First refresh writes the whole file via `PUT /api/context/user/reading-taste`.
+Subsequent refreshes use `PATCH` per section (but the metadata lines must
+be updated via a full-file `PUT`). Required structure:
+
+```markdown
+---
+type: user
+owner: shared
+updated: YYYY-MM-DD
+---
+# Reading Taste
+> Last updated: YYYY-MM-DD HH:MM
+> Sampled: N highlights across M books (window: last K weeks)
+> Highlights at last sweep: T   <!-- total in DB from /books/summary, used for delta check -->
+
+## Topics of Interest
+- 3–6 bullets. Concrete topics, not categories: "cognitive biases in
+  decision-making" not "psychology". Each bullet: one line.
+
+## Thinking Patterns
+- 3–5 bullets. How the user processes ideas, inferred from what they
+  highlight — e.g. "highlights counter-intuitive claims with supporting
+  evidence", "prefers concrete cases over abstractions", "marks passages
+  that challenge common wisdom".
+
+## Values & Recurring Questions
+- 3–5 bullets. Values or open questions the highlights keep returning
+  to — e.g. "tension between productivity and depth", "skepticism of
+  institutional incentives", "what makes work meaningful".
+
+## Preferred Formats
+- 1–3 bullets. Observed preferences: narrative nonfiction, research-heavy,
+  essay collections, short-form, etc. State only what the sample supports.
+
+## Book Candidates
+- 5–10 bullets. Rolling list of books the user might enjoy, written by
+  you based on the sampled highlights. Format each as:
+  `- <Title> — <Author>. Why: <1 sentence tying it to a specific pattern
+    above>.`
+  Do not repeat books already in `books` (any status). Prefer ≤2 per author.
+  Replace the full list each weekly sweep (append-style drift produces
+  stale duplicates).
+```
+
+### Rules for the taste profile
+
+- **Stay grounded in sampled highlights.** Every claim in Topics / Thinking
+  Patterns / Values should be traceable to specific passages you read.
+  When writing, mentally annotate each bullet with the highlight(s) that
+  justify it — if you cannot, drop the bullet.
+- **No moralizing or judgement.** Record what the user is drawn to, not
+  whether those interests are "good". Avoid adjectives that evaluate the
+  user ("enlightened", "shallow").
+- **Avoid one-shot artifacts.** A single standout highlight isn't a
+  pattern. Look for themes across ≥2 books before recording.
+- **Language: English only.** Per project convention — even if the source
+  highlights are in another language, summarize in English.
+- **Silent update.** Never notify the user about taste-profile changes.
+
+### PATCH patterns
+
+Replace a single section (snake_case the heading):
+
+```bash
+curl -s -X PATCH http://localhost:8321/api/context/user/reading-taste \
+  -H 'Content-Type: application/json' \
+  -d '{"section": "topics_of_interest", "mode": "replace", "content": "- cognitive biases\n- systems design"}'
+```
+
+Replace the full file (first time, or after a major reset):
+
+```bash
+curl -s -X PUT http://localhost:8321/api/context/user/reading-taste \
+  -H 'Content-Type: application/json' \
+  -d '{"content": "---\ntype: user\nowner: shared\nupdated: 2026-04-21\n---\n# Reading Taste\n> Last updated: 2026-04-16 09:00\n> Sampled: 87 highlights across 8 books (window: last 12 weeks)\n> Highlights at last sweep: 245\n\n## Topics of Interest\n- ...\n..."}'
+```
+
+Update both the `Last updated` line and the `Highlights at last sweep`
+line on every refresh. Section-level `PATCH` does not touch the top
+metadata — if only sections changed, still issue one `PUT` at the end of
+the sweep to write the refreshed metadata and YAML `updated` date.
+
+### First-write registration (_index.md)
+
+The `user/_index.md` file indexes available topic files. When
+creating `reading-taste.md` for the first time (GET returned 404),
+append a one-line entry to the index so other flows can discover it:
+
+```bash
+curl -s -X PATCH http://localhost:8321/api/context/user/_index \
+  -H 'Content-Type: application/json' \
+  -d '{"section": "topics", "mode": "append", "content": "- reading-taste — derived taste profile + rolling book candidates (updated weekly)"}'
+```
+
+The section name (`topics` above) depends on the existing `_index.md`
+shape; fetch it first and append under the most natural heading. Do
+NOT overwrite existing index content.
+
+---
+
+## Book Recommendations
+
+The weekly sweep writes recommendations into the `Book Candidates`
+section of `reading-taste.md` (see above). Do **not** create a separate
+`recommendations.md` — the candidate list belongs with the taste it was
+derived from.
+
+### How to propose candidates
+
+- Use your own book knowledge keyed by the sampled highlights. This is
+  reasoning from the user's demonstrated taste, not a lookup — no
+  external API.
+- Avoid recommending books already in the `books` table (any status).
+  Fetch the existing library once before writing the final list. For
+  libraries larger than 200 books, paginate with
+  `?limit=200&offset=0`, `&offset=200`, … until `hasMore === false`,
+  and merge the titles into a single exclusion set.
+- Tie each recommendation to a specific pattern from Topics / Thinking /
+  Values. A recommendation with no pattern-justification is a generic
+  suggestion and should be dropped.
+- Prefer books the user is likely unaware of — not the usual-suspects
+  that trend on social media.
+
+### Weekly user-facing hint (optional)
+
+If the silent gate in Phase 4 of the weekly review does **not** trigger
+and the taste file gained ≥1 genuinely new candidate this sweep, you
+MAY add a single optional line to the weekly notification in the form:
+`Reading pick: <Title> — <1-clause why>.`
+
+Do not force a line just because recommendations were updated. The
+silent-default principle applies: omit if the pick would feel like
+filler.

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

@@ -0,0 +1,134 @@
+---
+name: receipts
+description: Load when the user asks about receipts/invoices, tax-prep needs an annual list, or an unsaved receipt should be filed.
+when_to_use: Downloads Gmail-observer-flagged attachments to the user's external Obsidian vault, separate from the agent's primary management store.
+allowed-tools:
+  - Bash(curl *)
+  - Read
+---
+
+# Receipt & Document Manager
+
+The daemon's Gmail observer scans travel-booking emails for PDF/image
+attachments and can retain previously detected generic documents.
+Attachment metadata is stored in the `receipts` SQLite table. Actual files
+are downloaded on demand and can be saved to the user's **external**
+Obsidian vault (separate from the agent's primary management store).
+
+## When to Use
+
+- **User asks about receipts**: list detected receipts, check save status.
+- **Tax preparation season**: generate annual receipt list, save unsaved receipts.
+- **Monthly/yearly review**: report on receipt collection completeness.
+
+## Workflow
+
+1. Fetch receipt list from `/api/receipts`.
+2. To save a receipt to the external Obsidian vault, download via
+   `/api/receipts/:id/download` then save to the vault via
+   `POST /api/obsidian/notes` and update the receipt record with the
+   vault-relative path via `PATCH /api/receipts/:id`. (`obsidianPath` is
+   a path inside the external vault, not the primary management store.)
+3. For tax preparation, filter by date range and category.
+
+---
+
+## API Reference
+
+Base URL: `http://localhost:8321`
+
+### GET /api/receipts
+
+List detected receipt attachments.
+
+```bash
+# All receipts
+curl -s "http://localhost:8321/api/receipts?limit=50"
+
+# Unsaved receipts only
+curl -s "http://localhost:8321/api/receipts?saved=false"
+
+# Filter by category
+curl -s "http://localhost:8321/api/receipts?category=document"
+```
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `category` | string | — | document, travel |
+| `saved` | boolean | — | true = saved to Obsidian, false = not yet saved |
+| `limit` | number | 50 | Max results (1–200) |
+
+Response:
+```json
+{
+  "receipts": [
+    {
+      "id": 1,
+      "gmailMessageId": "18f...",
+      "attachmentId": "ANGj...",
+      "filename": "receipt.pdf",
+      "mimeType": "application/pdf",
+      "sizeBytes": 45000,
+      "category": "document",
+      "obsidianPath": null,
+      "savedAt": null,
+      "createdAt": "2026-04-12T10:00:00Z"
+    }
+  ],
+  "total": 1
+}
+```
+
+### GET /api/receipts/summary
+
+Receipt statistics.
+
+```bash
+curl -s "http://localhost:8321/api/receipts/summary"
+```
+
+Response:
+```json
+{
+  "total": 25,
+  "saved": 10,
+  "unsaved": 15,
+  "byCategory": [
+    { "category": "document", "count": 23 },
+    { "category": "travel", "count": 2 }
+  ]
+}
+```
+
+### POST /api/receipts/:id/download
+
+Download the actual attachment file from Gmail.
+
+```bash
+curl -s -X POST "http://localhost:8321/api/receipts/1/download" -o receipt.pdf
+```
+
+### PATCH /api/receipts/:id
+
+Update receipt metadata (change category or mark as saved).
+
+```bash
+# Mark as saved to Obsidian
+curl -s -X PATCH "http://localhost:8321/api/receipts/1" \
+  -H "Content-Type: application/json" \
+  -d '{"obsidianPath": "receipts/2026/04/amazon-receipt.pdf"}'
+
+# Reclassify a receipt
+curl -s -X PATCH "http://localhost:8321/api/receipts/1" \
+  -H "Content-Type: application/json" \
+  -d '{"category": "travel"}'
+```
+
+---
+
+## External Obsidian Vault Save Convention
+
+Save receipts to: `receipts/YYYY/MM/<merchant>-<date>.<ext>` inside the
+external Obsidian vault.
+
+Example: `receipts/2026/04/amazon-2026-04-12.pdf`