@opentil/cli 1.11.0

package/templates/skill/references/api.md

@@ -0,0 +1,465 @@
+# API Reference
+
+Base URL: `https://opentil.ai/api/v1`
+
+All requests require a Bearer token:
+
+```
+Authorization: Bearer $OPENTIL_TOKEN
+```
+
+## POST /entries -- Create Entry
+
+### Request Body
+
+All fields are nested under `entry`. Additionally, `tag_names` and `category_name` are accepted at the `entry` level as convenience parameters.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `content` | string | yes | Markdown body (max 100,000 chars) |
+| `title` | string | no | Entry title (max 200 chars). Auto-generates slug if omitted. |
+| `slug` | string | no | Custom URL slug. Auto-generated from title if omitted. |
+| `tag_names` | array | no | 1-3 lowercase tags, e.g. `["go", "concurrency"]` |
+| `category_name` | string | no | Category name. Only include if the user explicitly specifies one. |
+| `category_id` | integer | no | Category ID (alternative to `category_name`). |
+| `published` | boolean | no | `false` for draft (default), `true` to publish immediately. |
+| `published_at` | datetime | no | ISO 8601 timestamp. Only relevant when publishing. |
+| `visibility` | string | no | `public` (default), `unlisted`, or `private` |
+| `summary` | string | no | AI-generated summary for listing pages (max 500 chars) |
+| `meta_description` | string | no | SEO meta description |
+| `meta_image` | string | no | URL for social sharing image |
+| `lang` | string | no | Language code (see Supported Languages below) |
+
+### Supported Languages
+
+`en`, `zh-CN`, `zh-TW`, `ja`, `ko`, `es`, `fr`, `de`, `pt-BR`, `pt`, `ru`, `ar`, `bs`, `da`, `nb`, `pl`, `th`, `tr`, `it`
+
+### 201 Response (EntrySerializer)
+
+```json
+{
+  "id": "1234567890",
+  "title": "Go interfaces are satisfied implicitly",
+  "slug": "go-interfaces-are-satisfied-implicitly",
+  "content": "In Go, a type implements an interface...",
+  "content_html": "<p>In Go, a type implements an interface...</p>",
+  "published": false,
+  "published_at": null,
+  "first_published_at": null,
+  "visibility": "public",
+  "hidden": false,
+  "summary": null,
+  "meta_description": null,
+  "meta_image": null,
+  "lang": "en",
+  "views_count": 0,
+  "unique_views_count": 0,
+  "category_id": null,
+  "category": null,
+  "tag_names": ["go", "interfaces"],
+  "source": "human",
+  "agent_name": "Claude Code",
+  "agent_model": "Claude Opus 4.6",
+  "url": "https://opentil.ai/@username/go-interfaces-are-satisfied-implicitly",
+  "created_at": "2026-02-10T14:30:22Z",
+  "updated_at": "2026-02-10T14:30:22Z"
+}
+```
+
+Use the `url` field for the Review link in result messages.
+
+## GET /entries -- List Entries
+
+List entries for the authenticated user. Requires `read:entries` scope.
+
+```
+GET /entries?status=published&per_page=20&q=go
+```
+
+| Param | Description |
+|-------|-------------|
+| `status` | `published`, `draft`, or `scheduled` |
+| `q` | Search by title (case-insensitive partial match) |
+| `tag` | Filter by tag slug |
+| `category_id` | Filter by category ID |
+| `uncategorized` | `true` to filter uncategorized entries |
+| `per_page` | Results per page (max 100, default 20) |
+| `page` | Page number |
+
+### Response (EntryListSerializer)
+
+```json
+{
+  "data": [
+    {
+      "id": "1234567890",
+      "title": "Go interfaces are satisfied implicitly",
+      "slug": "go-interfaces-are-satisfied-implicitly",
+      "excerpt": "In Go, a type implements an interface by implementing...",
+      "published": true,
+      "published_at": "2026-02-10T14:30:22Z",
+      "first_published_at": "2026-02-10T14:30:22Z",
+      "visibility": "public",
+      "views_count": 42,
+      "unique_views_count": 35,
+      "category_id": null,
+      "category_name": null,
+      "tag_names": ["go", "interfaces"],
+      "source": "human",
+      "agent_name": "Claude Code",
+      "agent_model": "Claude Opus 4.6",
+      "created_at": "2026-02-10T14:30:22Z",
+      "updated_at": "2026-02-10T14:30:22Z"
+    }
+  ],
+  "meta": {
+    "current_page": 1,
+    "total_pages": 1,
+    "total_count": 1,
+    "per_page": 20
+  }
+}
+```
+
+## GET /entries/drafts
+
+Shorthand for listing draft entries. Requires `read:entries` scope.
+
+Returns the same response format as `GET /entries` but filtered to drafts, ordered by `updated_at` descending.
+
+## GET /entries/:id -- Show Entry
+
+Fetch a single entry. Requires `read:entries` scope.
+
+Returns the full EntrySerializer response (same as 201 response above).
+
+## PATCH /entries/:id -- Update Entry
+
+Update an entry. Requires `write:entries` scope.
+
+### Request Body
+
+Same fields as POST, all optional. Only include fields that are changing.
+
+```json
+{
+  "entry": {
+    "title": "Updated title",
+    "content": "Updated content...",
+    "tag_names": ["go", "interfaces", "type-system"]
+  }
+}
+```
+
+### 200 Response
+
+Returns the full EntrySerializer response with updated fields.
+
+## DELETE /entries/:id -- Delete Entry
+
+Permanently delete an entry. Requires `delete:entries` scope.
+
+### 200 Response
+
+```json
+{
+  "message": "Entry deleted"
+}
+```
+
+## POST /entries/:id/publish
+
+Publish a draft entry. Requires `write:entries` scope. No request body needed.
+
+Returns the full EntrySerializer response with `published: true`.
+
+## POST /entries/:id/unpublish
+
+Unpublish a published entry (revert to draft). Requires `write:entries` scope. No request body needed.
+
+Returns the full EntrySerializer response with `published: false`.
+
+## Error Handling
+
+### Error Response Format
+
+```json
+{
+  "error": {
+    "type": "validation_error",
+    "code": "validation_failed",
+    "message": "Validation failed",
+    "details": [{"field": "title", "message": "Title can't be blank"}]
+  }
+}
+```
+
+### Error Codes
+
+| Status | Code | Action |
+|--------|------|--------|
+| 401 | `unauthorized` | Token invalid or expired. Save locally (for capture commands). Then follow the inline re-authentication flow defined in SKILL.md Error Handling — prompt to reconnect if token is from `~/.til/credentials`, or show env var guidance if from `$OPENTIL_TOKEN`. |
+| 403 | `insufficient_scope` | Token lacks required scope. Show which scope is needed. |
+| 404 | `not_found` | Entry does not exist or belongs to another user. |
+| 422 | `validation_failed` | Parse `details` array, auto-fix, and retry once. Save locally if retry fails. |
+| 429 | `rate_limited` | Rate limit exceeded. Save locally. Retry after `X-RateLimit-Reset`. |
+| 5xx | -- | Server error. Save locally. |
+
+### 422 Auto-Fix Retry Logic
+
+When a 422 is returned, inspect the `details` array and attempt to fix:
+
+1. `title` too long -> truncate to 200 chars
+2. `lang` invalid -> fall back to `en`
+3. `slug` already taken -> append `-2` (or increment)
+4. `tag_names` invalid -> remove offending tags, keep valid ones
+5. `content` too long -> truncate to 100,000 chars
+
+After fixing, retry the POST **once**. If the retry also returns 422, save locally and report the error.
+
+## GET /site -- Site Info
+
+Fetch the authenticated user's site details. Requires `read:entries` scope.
+
+### Response (SiteDetailSerializer)
+
+```json
+{
+  "username": "hong",
+  "title": "Hong's TIL",
+  "bio": "Learning something new every day",
+  "timezone": "Asia/Shanghai",
+  "locale": "en",
+  "entries_count": 28,
+  "published_entries_count": 15,
+  "categories_count": 3,
+  "custom_domain": null,
+  "domain_verified": false,
+  "discoverable": true,
+  "theme_slug": "default",
+  "theme_mode": "auto",
+  "last_posted_at": "2026-02-10T14:30:22Z",
+  "created_at": "2025-06-01T00:00:00Z",
+  "updated_at": "2026-02-10T14:30:22Z"
+}
+```
+
+- `entries_count`: total entries (including drafts)
+- `published_entries_count`: published entries only
+
+Used by `/til status` to display site info.
+
+## GET /tags -- List Tags
+
+List tags for the authenticated user's site. Requires `read:entries` scope.
+
+```
+GET /tags?sort=popular&per_page=20
+```
+
+| Param | Description |
+|-------|-------------|
+| `sort` | `popular` (default, by taggings count) or `alphabetical` |
+| `per_page` | Results per page (max 100, default 20) |
+| `page` | Page number |
+| `with_entries` | `true` to only return tags that have entries |
+
+### Response (TagSerializer)
+
+```json
+{
+  "data": [
+    {
+      "id": "123",
+      "name": "go",
+      "slug": "go",
+      "taggings_count": 8,
+      "created_at": "2025-06-15T10:00:00Z"
+    }
+  ],
+  "meta": {
+    "current_page": 1,
+    "total_pages": 1,
+    "total_count": 12,
+    "per_page": 20
+  }
+}
+```
+
+Note: `taggings_count` is the global usage count across all entries on the site.
+
+Used by `/til tags` to display tag usage.
+
+## GET /categories -- List Categories
+
+List categories (topics) for the authenticated user's site. Requires `read:entries` scope.
+
+```
+GET /categories
+```
+
+### Response (CategorySerializer)
+
+```json
+{
+  "data": [
+    {
+      "id": "456",
+      "name": "Backend",
+      "slug": "backend",
+      "description": "Server-side topics",
+      "entries_count": 12,
+      "position": 0,
+      "created_at": "2025-06-15T10:00:00Z"
+    }
+  ]
+}
+```
+
+Note: `entries_count` is the site-level count of entries in that category.
+
+Used by `/til categories` to display category listing.
+
+## Rate Limits
+
+- Authenticated: 5,000 requests/hour
+- Unauthenticated: 60 requests/hour
+
+Rate limit info is returned in response headers:
+
+| Header | Description |
+|--------|-------------|
+| `X-RateLimit-Limit` | Maximum requests per window |
+| `X-RateLimit-Remaining` | Requests remaining in current window |
+| `X-RateLimit-Reset` | Unix timestamp when the window resets |
+
+When `429` is received, save the draft locally and inform the user. Do not retry automatically -- the user's workflow should not be blocked by rate limits.
+
+## Device Flow (OAuth)
+
+These endpoints do not require a Bearer token. Used by `/til auth` to obtain a token via browser authorization.
+
+### POST /oauth/device/code
+
+Create a device authorization code.
+
+```
+POST /api/v1/oauth/device/code
+Content-Type: application/json
+
+{ "scopes": ["read", "write"] }
+```
+
+**200 Response:**
+
+```json
+{
+  "device_code": "uuid-string",
+  "user_code": "XXXX-YYYY",
+  "verification_uri": "https://opentil.ai/device",
+  "expires_in": 900,
+  "interval": 5
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `device_code` | Opaque code used to poll for the token |
+| `user_code` | Human-readable code displayed to the user |
+| `verification_uri` | URL where the user authorizes the device |
+| `expires_in` | Seconds until the device code expires |
+| `interval` | Minimum polling interval in seconds |
+
+### POST /oauth/device/token
+
+Poll for an access token after the user authorizes.
+
+```
+POST /api/v1/oauth/device/token
+Content-Type: application/json
+
+{ "device_code": "uuid-string", "grant_type": "urn:ietf:params:oauth:grant-type:device_code" }
+```
+
+**200 Response (authorized):**
+
+```json
+{
+  "access_token": "til_xxx...",
+  "token_type": "bearer",
+  "scope": "read write"
+}
+```
+
+**400 Response (pending):**
+
+```json
+{
+  "error": {
+    "code": "authorization_pending",
+    "message": "The user has not yet authorized this device"
+  }
+}
+```
+
+**Error codes:**
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| `authorization_pending` | User hasn't authorized yet | Continue polling |
+| `slow_down` | Polling too fast | Increase interval by 5 seconds |
+| `expired_token` | Device code expired | Stop polling, show timeout message |
+| `invalid_grant` | Invalid device code | Stop polling, show error |
+
+## Credential Storage
+
+After a successful device flow, credentials are stored locally in `~/.til/credentials` as YAML.
+
+### File Format
+
+```yaml
+active: personal
+profiles:
+  personal:
+    token: til_abc...
+    nickname: hong
+    site_url: https://opentil.ai/@hong
+    host: https://opentil.ai
+  work:
+    token: til_xyz...
+    nickname: hong-corp
+    site_url: https://opentil.ai/@hong-corp
+    host: https://opentil.ai
+```
+
+### Field Reference
+
+| Field | Level | Description |
+|-------|-------|-------------|
+| `active` | top | Name of the currently active profile |
+| `profiles` | top | Map of profile name → profile object |
+| `token` | profile | Bearer token (starts with `til_`) |
+| `nickname` | profile | Username from `GET /site` response (`username` field) |
+| `site_url` | profile | Public site URL, e.g. `https://opentil.ai/@hong` |
+| `host` | profile | API host, e.g. `https://opentil.ai` |
+
+### Backward Compatibility
+
+Old format (`~/.til/credentials` containing only a plain text token):
+
+```
+til_abc123...
+```
+
+On first read, detect the old format (file content starts with `til_` and contains no YAML structure). Migrate automatically:
+
+1. Read the token string
+2. `GET /site` with the token to fetch `username`
+   - On success: use `username` as profile name, populate `nickname` and `site_url`
+   - On failure (401/network): use `default` as profile name, leave `nickname` and `site_url` empty
+3. Write back as YAML with the single profile set as `active`
+4. Preserve file permissions (`chmod 600`)
+
+### File Permissions
+
+Always set `~/.til/credentials` to `chmod 600` (owner read/write only) after any write operation. Create `~/.til/` directory with `chmod 700` if it doesn't exist.

package/templates/skill/references/auto-detection.md

@@ -0,0 +1,145 @@
+# Auto-Detection Guide
+
+This document details how the Agent proactively detects TIL-worthy moments during work sessions.
+
+## Trigger Examples
+
+### Debugging uncovered a non-obvious root cause
+
+Good example: "The memory leak was caused by a goroutine referencing a closure variable that held the entire HTTP request body, not just the header field we needed."
+
+Bad example: "Fixed the null pointer error by adding a nil check." (Obvious fix, no insight.)
+
+### Language/framework behavior contradicts common assumptions
+
+Good example: "Python's `defaultdict` calls the factory function even when you're just reading a key with `d[key]` -- it doesn't distinguish reads from writes."
+
+Bad example: "JavaScript has both `==` and `===`." (Well-known, not surprising.)
+
+### Refactoring revealed a superior pattern
+
+Good example: "Replacing the chain of `if-else` handlers with a strategy map reduced the function from 80 lines to 15 and made adding new handlers a one-line change."
+
+Bad example: "Renamed variables to be more descriptive." (Cosmetic, no pattern insight.)
+
+### Performance optimization with measurable results
+
+Good example: "Adding a compound index on (user_id, created_at) reduced the dashboard query from 2.3s to 12ms."
+
+Bad example: "Used caching to make things faster." (Vague, no specifics.)
+
+### Obscure but useful tool flag or API parameter
+
+Good example: "git diff --word-diff=color shows inline character-level changes instead of full-line diffs, perfect for reviewing prose changes."
+
+Bad example: "Used git log to see commit history." (Basic, widely known.)
+
+### Two technologies interacting unexpectedly
+
+Good example: "When using PostgreSQL's `jsonb_path_query` with a Rails `where` clause, the query planner can't use the GIN index because Rails wraps the expression in a type cast."
+
+Bad example: "Used Redis with Rails for caching." (Standard pattern, no surprise.)
+
+### Upgrade/migration breaking changes
+
+Good example: "Ruby 3.2 changed `Struct` keyword arguments to be required by default -- all existing `Struct.new` calls with optional keyword args silently broke."
+
+Bad example: "Updated Node from v18 to v20." (Fact, no insight.)
+
+## What NOT to Detect
+
+Do not suggest TIL capture for:
+
+- Standard usage of tools/APIs (reading docs, running commands)
+- Configuration that works as documented
+- Bugs caused by typos or simple mistakes
+- Widely known best practices (use environment variables, write tests, etc.)
+- Anything the user already seems to know well
+- Tasks where the user is actively frustrated or stressed -- wait for resolution
+
+## Rate Limiting State Machine
+
+```
+[IDLE] ---(TIL-worthy moment detected)---> [EVALUATING]
+  ^                                              |
+  |                                    (check constraints)
+  |                                              |
+  |                              +-------+-------+
+  |                              |               |
+  |                     (constraints        (constraints
+  |                       not met)             met)
+  |                              |               |
+  |                              v               v
+  +----(stay idle)----------[IDLE]         [SUGGESTED]
+                                              |
+                                    +---------+---------+
+                                    |                   |
+                              (user accepts)      (user declines
+                                    |             or ignores)
+                                    v                   v
+                               [CAPTURED]        [DONE_FOR_SESSION]
+                                    |
+                                    v
+                             [DONE_FOR_SESSION]
+```
+
+**Constraints checked in EVALUATING state:**
+
+1. Has a suggestion already been made this session? → If yes, stay IDLE
+2. Is the user in the middle of active problem-solving? → If yes, stay IDLE
+3. Is this a natural pause point (resolution or task boundary)? → If no, stay IDLE
+
+Once in DONE_FOR_SESSION, the agent never suggests again until a new session starts.
+
+## Suggestion Format
+
+Append the suggestion at the end of your normal response. Never interrupt the workflow with a standalone suggestion message.
+
+**Template:**
+```
+💡 TIL: [concise title of the insight]
+   Tags: [tag1, tag2] · Capture? (yes/no)
+```
+
+**Example** (debugging root cause):
+```
+...so the memory leak was caused by the goroutine holding a reference to the entire request body.
+
+💡 TIL: Goroutine closures can silently retain large objects, causing memory leaks
+   Tags: go, concurrency · Capture? (yes/no)
+```
+
+**Example** (performance optimization):
+```
+...the compound index on (user_id, created_at) reduced the query from 2.3s to 12ms.
+
+💡 TIL: Compound indexes with the right column order can yield 100x+ query speedups
+   Tags: postgresql, indexing · Capture? (yes/no)
+```
+
+**Example** (migration breaking change):
+```
+...Ruby 3.2 changed Struct keyword arguments to be required by default.
+
+💡 TIL: Ruby 3.2 makes Struct keyword args required by default, silently breaking existing code
+   Tags: ruby, migration · Capture? (yes/no)
+```
+
+## Single Confirmation Flow
+
+```
+Agent: [normal response content]
+
+       💡 TIL: [concise title]
+          Tags: [tags] · Capture? (yes/no)
+
+User:  yes / y / ok / sure
+
+Agent: [Generates full entry: title, body, tags, lang]
+       [POST to API or save locally]
+       [Show result message]
+```
+
+The suggestion itself is the candidate. When the user says yes, the agent generates the full entry directly — no extract flow, no draft review step.
+
+If the user ignores the suggestion, says "no", or continues with another topic, treat it as decline. Move on and do not ask again this session.