@opentil/cli 1.11.0

package/templates/skill/references/local-drafts.md

@@ -0,0 +1,142 @@
+# Local Drafts & Sync Protocol
+
+When the API is unavailable or no token is configured, TIL entries are saved locally. This document covers the full local draft lifecycle.
+
+## Directory Structure
+
+```
+~/.til/
+  drafts/
+    20260210-143022-go-interfaces.md
+    20260210-150415-postgresql-gin-index.md
+    20260211-091200-css-has-selector.md
+```
+
+All platforms use `~/.til/drafts/`. Create the directory if it does not exist.
+
+## File Format
+
+Filename: `YYYYMMDD-HHMMSS-<slug>.md`
+
+The slug is derived from the title (lowercase, hyphens, no special chars, max 50 chars).
+
+```markdown
+---
+title: "Go interfaces are satisfied implicitly"
+tags: [go, interfaces]
+lang: en
+summary: "Go types implement interfaces implicitly by implementing their methods, with no explicit declaration needed."
+source: human
+agent_name: Claude Code
+agent_model: Claude Opus 4.6
+profile: personal
+---
+
+In Go, a type implements an interface by implementing its methods.
+There is no explicit `implements` keyword...
+```
+
+### Frontmatter Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | string | Entry title |
+| `tags` | array | Tag list |
+| `lang` | string | Language code |
+| `summary` | string | AI-generated summary for listing pages (max 500 chars) |
+| `source` | string | `human` (from `/til`) or `agent` (from auto-detection) |
+| `agent_name` | string | Agent display name, e.g. `Claude Code` (optional) |
+| `agent_model` | string | Human-readable model name, e.g. `Claude Opus 4.6` (optional) |
+| `profile` | string | Active profile name at save time (optional). Used during sync to determine which account's token to use. Omitted when no profiles are configured. |
+
+The `source`, `agent_name`, and `agent_model` fields preserve attribution so that when syncing to the API, the correct headers and tags can be applied.
+
+The `profile` field ensures drafts are synced to the correct account in multi-profile setups.
+
+## Sync Protocol
+
+When a successful API call is made (201 response), check for pending local drafts:
+
+### Step 1: Detect Pending Drafts
+
+```
+List files in ~/.til/drafts/ matching *.md
+```
+
+If no files exist, skip sync entirely.
+
+### Step 2: Offer to Sync
+
+```
+Found 3 local drafts from before. Sync them to OpenTIL?
+```
+
+Wait for user confirmation. If the user declines, do not ask again this session.
+
+### Step 3: Sync Each Draft
+
+For each `.md` file in `~/.til/drafts/`:
+
+1. Parse the frontmatter (title, tags, lang, source, agent_name, agent_model, profile)
+2. **Resolve token for this draft** (profile matching):
+   - If `$OPENTIL_TOKEN` is set → always use it (env var overrides all profiles)
+   - If `profile` field is present → look up that profile's token in `~/.til/credentials`
+     - Profile found → use its token
+     - Profile not found → skip this draft, report: `Skipped: profile "work" not found (/til auth list)`
+   - If `profile` field is absent (old drafts) → use the current active profile's token
+3. Read the content body (everything after the second `---`)
+4. POST to API (using the resolved token):
+   - Set `published: false`
+   - Set `X-OpenTIL-Source` header based on `source` field
+   - Set `X-OpenTIL-Agent` header from `agent_name` field (if present)
+   - Set `X-OpenTIL-Model` header from `agent_model` field (if present)
+   - Add `agent-assisted` tag if `source` is `agent`
+5. On 201 success: delete the local file
+6. On failure: keep the local file, record the error
+
+### Step 4: Report Results
+
+**All succeeded:**
+```
+Synced 3 local drafts to OpenTIL
+
+  + Go defer runs in LIFO order
+  + PostgreSQL JSONB indexes support GIN operators
+  + CSS :has() selector enables parent selection
+```
+
+**Partial failure:**
+```
+Synced 2 of 3 local drafts
+
+  + Go defer runs in LIFO order
+  + PostgreSQL JSONB indexes support GIN operators
+  x CSS :has() selector enables parent selection (validation error)
+    Kept at: ~/.til/drafts/20260210-143022-css-has-selector.md
+```
+
+## First-Run Guide Template
+
+On the first local save in a session (when no token is found):
+
+```
+TIL captured
+
+  Title:  Go interfaces are satisfied implicitly
+  Tags:   go, interfaces
+  File:   ~/.til/drafts/20260210-143022-go-interfaces.md
+
+Sync to OpenTIL? Run: /til auth
+```
+
+On subsequent local saves in the same session, use the short form:
+
+```
+TIL captured
+
+  Title:  Go interfaces are satisfied implicitly
+  Tags:   go, interfaces
+  File:   ~/.til/drafts/20260210-143022-go-interfaces.md
+```
+
+Track "first save shown" as session state. Reset on each new session.