@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/skill/industrial-brutalist-ui/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: industrial-brutalist-ui
+description: Use INSTEAD OF design-taste-frontend when user requests brutalist, military-terminal, or raw mechanical aesthetics. Swiss typographic print meets utilitarian color. For data-heavy dashboards or editorial sites needing declassified-blueprint energy.
+---
+
+## When to Use
+
+- When the user requests brutalist, military-terminal, or raw mechanical aesthetics
+- For data-heavy dashboards or editorial sites needing declassified-blueprint energy
+- Instead of design-taste-frontend when utilitarian aesthetics are requested
+
+## When NOT to Use
+
+- For consumer-facing marketing or e-commerce sites
+- When clean, minimalist, or luxury aesthetics are requested
+- For accessibility-critical applications where brutalist patterns may reduce readability
+
+
+# SKILL: Industrial Brutalism & Tactical Telemetry UI
+
+## 1. Skill Meta
+**Name:** Industrial Brutalism & Tactical Telemetry Interface Engineering
+**Description:** Advanced proficiency in architecting web interfaces that synthesize mid-century Swiss Typographic design, industrial manufacturing manuals, and retro-futuristic aerospace/military terminal interfaces. This discipline requires absolute mastery over rigid modular grids, extreme typographic scale contrast, purely utilitarian color palettes, and the programmatic simulation of analog degradation (halftones, CRT scanlines, bitmap dithering). The objective is to construct digital environments that project raw functionality, mechanical precision, and high data density, deliberately discarding conventional consumer UI patterns.
+
+## 2. Visual Archetypes
+The design system operates by merging two distinct but highly compatible visual paradigms. **Pick ONE per project and commit to it. Do not alternate or mix both modes within the same interface.**
+
+### 2.1 Swiss Industrial Print
+Derived from 1960s corporate identity systems and heavy machinery blueprints.
+*   **Characteristics:** High-contrast light modes (newsprint/off-white substrates). Reliance on monolithic, heavy sans-serif typography. Unforgiving structural grids outlined by visible dividing lines. Aggressive, asymmetric use of negative space punctuated by oversized, viewport-bleeding numerals or letterforms. Heavy use of primary red as an alert/accent color.
+
+### 2.2 Tactical Telemetry & CRT Terminal
+Derived from classified military databases, legacy mainframes, and aerospace Heads-Up Displays (HUDs).
+*   **Characteristics:** Dark mode exclusivity. High-density tabular data presentation. Absolute dominance of monospaced typography. Integration of technical framing devices (ASCII brackets, crosshairs). Application of simulated hardware limitations (phosphor glow, scanlines, low bit-depth rendering).
+
+## 3. Typographic Architecture
+Typography is the primary structural and decorative infrastructure. Imagery is secondary. The system demands extreme variance in scale, weight, and spacing.
+
+### 3.1 Macro-Typography (Structural Headers)
+*   **Classification:** Neo-Grotesque / Heavy Sans-Serif.
+*   **Optimal Web Fonts:** Neue Haas Grotesk (Black), Inter (Extra Bold/Black), Archivo Black, Roboto Flex (Heavy), Monument Extended.
+*   **Implementation Parameters:**
+    *   **Scale:** Deployed at massive scales using fluid typography (e.g., `clamp(4rem, 10vw, 15rem)`).
+    *   **Tracking (Letter-spacing):** Extremely tight, often negative (`-0.03em` to `-0.06em`), forcing glyphs to form solid architectural blocks.
+    *   **Leading (Line-height):** Highly compressed (`0.85` to `0.95`).
+    *   **Casing:** Exclusively uppercase for structural impact.
+
+### 3.2 Micro-Typography (Data & Telemetry)
+*   **Classification:** Monospace / Technical Sans.
+*   **Optimal Web Fonts:** JetBrains Mono, IBM Plex Mono, Space Mono, VT323, Courier Prime.
+*   **Implementation Parameters:**
+    *   **Scale:** Fixed and small (`10px` to `14px` / `0.7rem` to `0.875rem`).
+    *   **Tracking:** Generous (`0.05em` to `0.1em`) to simulate mechanical typewriter spacing or terminal matrices.
+    *   **Leading:** Standard to tight (`1.2` to `1.4`).
+    *   **Casing:** Exclusively uppercase. Used for all metadata, navigation, unit IDs, and coordinates.
+
+### 3.3 Textural Contrast (Artistic Disruption)
+*   **Classification:** High-Contrast Serif.
+*   **Optimal Web Fonts:** Playfair Display, EB Garamond, Times New Roman.
+*   **Implementation Parameters:** Used exceedingly sparingly. Must be subjected to heavy post-processing (halftone filters, 1-bit dithering) to degrade vector perfection and create textural juxtaposition against the clean sans-serifs.
+
+## 4. Color System
+The color architecture is uncompromising. Gradients, soft drop shadows, and modern translucency are strictly prohibited. Colors simulate physical media or primitive emissive displays.
+
+**CRITICAL: Choose ONE substrate palette per project and use it consistently. Never mix light and dark substrates within the same interface.**
+
+### If Swiss Industrial Print (Light):
+*   **Background:** `#F4F4F0` or `#EAE8E3` (Matte, unbleached documentation paper).
+*   **Foreground:** `#050505` to `#111111` (Carbon Ink).
+*   **Accent:** `#E61919` or `#FF2A2A` (Aviation/Hazard Red). This is the ONLY accent color. Used for strike-throughs, thick structural dividing lines, or vital data highlights.
+
+### If Tactical Telemetry (Dark):
+*   **Background:** `#0A0A0A` or `#121212` (Deactivated CRT. Avoid pure `#000000`).
+*   **Foreground:** `#EAEAEA` (White phosphor). This is the primary text color.
+*   **Accent:** `#E61919` or `#FF2A2A` (Aviation/Hazard Red). Same red, same rules.
+*   **Terminal Green (`#4AF626`):** Optional. Use ONLY for a single specific UI element (e.g., one status indicator or one data readout) — never as a general text color. If it doesn't serve a clear purpose, omit it entirely.
+
+## 5. Layout and Spatial Engineering
+The layout must appear mathematically engineered. It rejects conventional web padding in favor of visible compartmentalization.
+
+*   **The Blueprint Grid:** Strict adherence to CSS Grid architectures. Elements do not float; they are anchored precisely to grid tracks and intersections.
+*   **Visible Compartmentalization:** Extensive utilization of solid borders (`1px` or `2px solid`) to delineate distinct zones of information. Horizontal rules (`<hr>`) frequently span the entire container width to segregate operational units.
+*   **Bimodal Density:** Layouts oscillate between extreme data density (tightly packed monospace metadata clustered together) and vast expanses of calculated negative space framing macro-typography.
+*   **Geometry:** Absolute rejection of `border-radius`. All corners must be exactly 90 degrees to enforce mechanical rigidity.
+
+## 6. UI Components and Symbology
+Standard web UI conventions are replaced with utilitarian, industrial graphic elements.
+
+*   **Syntax Decoration:** Utilization of ASCII characters to frame data points.
+    *   *Framing:* `[ DELIVERY SYSTEMS ]`, `< RE-IND >`
+    *   *Directional:* `>>>`, `///`, `\\\\`
+*   **Industrial Markers:** Prominent integration of registration (`®`), copyright (`©`), and trademark (`™`) symbols functioning as structural geometric elements rather than legal text.
+*   **Technical Assets:** Integration of crosshairs (`+`) at grid intersections, repeating vertical lines (barcodes), thick horizontal warning stripes, and randomized string data (e.g., `REV 2.6`, `UNIT / D-01`) to simulate active mechanical processes.
+
+## 7. Textural and Post-Processing Effects
+To prevent the design from appearing purely digital, simulated analog degradation is engineered into the frontend via CSS and SVG filters.
+
+*   **Halftone and 1-Bit Dithering:** Transforming continuous-tone images or large serif typography into dot-matrix patterns. Achieved via pre-processing or CSS `mix-blend-mode: multiply` overlays combined with SVG radial dot patterns.
+*   **CRT Scanlines:** For terminal interfaces, applying a `repeating-linear-gradient` to the background to simulate horizontal electron beam sweeps (e.g., `repeating-linear-gradient(0deg, transparent, transparent 2px, rgba(0,0,0,0.1) 2px, rgba(0,0,0,0.1) 4px)`).
+*   **Mechanical Noise:** A global, low-opacity SVG static/noise filter applied to the DOM root to introduce a unified physical grain across both dark and light modes.
+
+## 8. Web Engineering Directives
+1.  **Grid Determinism:** Utilize `display: grid; gap: 1px;` with contrasting parent/child background colors to generate mathematically perfect, razor-thin dividing lines without complex border declarations.
+2.  **Semantic Rigidity:** Construct the DOM using precise semantic tags (`<data>`, `<samp>`, `<kbd>`, `<output>`, `<dl>`) to accurately reflect the technical nature of the telemetry.
+3.  **Typography Clamping:** Implement CSS `clamp()` functions exclusively for macro-typography to ensure massive text scales aggressively while maintaining structural integrity across viewports.

package/dist/template/.opencode/skill/jira/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: jira
+description: Use when interacting with Jira issues or Confluence docs — searching tickets, creating issues, updating status, or reading wiki pages. MUST load before any Atlassian integration. Requires network access to Atlassian MCP.
+version: 1.0.0
+tags: [integration, mcp, workflow]
+dependencies: []
+---
+
+# Jira & Confluence Integration (MCP)
+
+## When to Use
+
+- When you need to search or update Jira/Confluence content via Atlassian MCP.
+
+## When NOT to Use
+
+- When the project does not use Atlassian Cloud or MCP access is unavailable.
+
+
+## Key Features
+
+- **OAuth 2.1 Authorization** - Secure browser-based authentication
+- **Rovo Search** - Unified search across Jira and Confluence
+- **Real-time Data** - Direct connection to Atlassian Cloud
+- **Permission-aware** - Respects existing user access controls
+
+## Available Tools
+
+### Universal Search (Recommended)
+
+- `search` - **Rovo Search** - Search Jira and Confluence content (use this by default)
+- `fetch` - Get details by ARI (Atlassian Resource Identifier) from search results
+
+### Jira
+
+- `getJiraIssue` - Get issue details by key or ID
+- `createJiraIssue` - Create new issues
+- `editJiraIssue` - Update existing issues
+- `transitionJiraIssue` - Change issue status
+- `addCommentToJiraIssue` - Add comments to issues
+- `addWorklogToJiraIssue` - Log work time
+- `searchJiraIssuesUsingJql` - Search with JQL queries
+- `getTransitionsForJiraIssue` - Get available status transitions
+- `getVisibleJiraProjects` - List accessible projects
+- `getJiraProjectIssueTypesMetadata` - Get issue types for a project
+- `getJiraIssueTypeMetaWithFields` - Get field metadata for issue type
+- `getJiraIssueRemoteIssueLinks` - Get remote links
+- `lookupJiraAccountId` - Find user account IDs
+
+### Confluence
+
+- `getConfluencePage` - Get page content by ID
+- `createConfluencePage` - Create new pages
+- `updateConfluencePage` - Update existing pages
+- `searchConfluenceUsingCql` - Search with CQL queries
+- `getConfluenceSpaces` - List spaces
+- `getPagesInConfluenceSpace` - List pages in a space
+- `getConfluencePageDescendants` - Get child pages
+- `getConfluencePageFooterComments` - Get footer comments
+- `getConfluencePageInlineComments` - Get inline comments
+- `createConfluenceFooterComment` - Add footer comment
+- `createConfluenceInlineComment` - Add inline comment on specific text
+
+### Utility
+
+- `atlassianUserInfo` - Get current user info
+- `getAccessibleAtlassianResources` - Get cloudId for API calls
+
+## Quick Start
+
+### 1. Configuration
+
+The MCP server uses OAuth 2.1 - no API tokens needed. Configuration in `mcp.json`:
+
+```json
+{
+  "jira": {
+    "command": "npx",
+    "args": ["-y", "mcp-remote", "https://mcp.atlassian.com/v1/sse"]
+  }
+}
+```
+
+### 2. Get Cloud ID
+
+Most tools require a `cloudId`. Get it from your site URL or use the utility:
+
+```typescript
+// Get accessible resources and cloudId
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "getAccessibleAtlassianResources"),
+  (arguments = "{}"),
+);
+```
+
+Or use your site URL directly as cloudId (e.g., `"ibet.atlassian.net"`).
+
+### 3. Use MCP Tools
+
+```typescript
+// Universal search (recommended for discovery)
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "search"),
+  (arguments = '{"query": "authentication bug"}'),
+);
+
+// Get issue details
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "getJiraIssue"),
+  (arguments = '{"cloudId": "your-site.atlassian.net", "issueIdOrKey": "PROJ-123"}'),
+);
+
+// Search with JQL
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "searchJiraIssuesUsingJql"),
+  (arguments = '{"cloudId": "your-site.atlassian.net", "jql": "project = PROJ AND status = Open"}'),
+);
+
+// Create issue
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "createJiraIssue"),
+  (arguments =
+    '{"cloudId": "your-site.atlassian.net", "projectKey": "PROJ", "issueTypeName": "Bug", "summary": "Login fails on mobile"}'),
+);
+
+// Transition issue status
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "transitionJiraIssue"),
+  (arguments =
+    '{"cloudId": "your-site.atlassian.net", "issueIdOrKey": "PROJ-123", "transition": {"id": "21"}}'),
+);
+
+// Get Confluence page
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "getConfluencePage"),
+  (arguments = '{"cloudId": "your-site.atlassian.net", "pageId": "123456789"}'),
+);
+
+// Search Confluence with CQL
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "searchConfluenceUsingCql"),
+  (arguments = '{"cloudId": "your-site.atlassian.net", "cql": "title ~ \"Onboarding\""}'),
+);
+```
+
+## Common Workflows
+
+### Daily Standup
+
+```typescript
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "searchJiraIssuesUsingJql"),
+  (arguments =
+    '{"cloudId": "your-site.atlassian.net", "jql": "assignee = currentUser() AND updated >= -1d"}'),
+);
+```
+
+### Bug Triage
+
+```typescript
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "searchJiraIssuesUsingJql"),
+  (arguments =
+    '{"cloudId": "your-site.atlassian.net", "jql": "type = Bug AND priority in (High, Critical) AND status != Done"}'),
+);
+```
+
+### Sprint Planning
+
+```typescript
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "searchJiraIssuesUsingJql"),
+  (arguments =
+    '{"cloudId": "your-site.atlassian.net", "jql": "project = PROJ AND sprint in openSprints()"}'),
+);
+```
+
+### Quick Discovery with Rovo Search
+
+```typescript
+// Best for finding content when you don't know exact location
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "search"),
+  (arguments = '{"query": "authentication implementation"}'),
+);
+
+// Then fetch details using ARI from results
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "fetch"),
+  (arguments = '{"id": "ari:cloud:jira:cloudId:issue/10107"}'),
+);
+```
+
+## JQL Examples
+
+```sql
+-- My open issues
+assignee = currentUser() AND status != Done
+
+-- High priority bugs
+project = PROJ AND type = Bug AND priority in (High, Critical)
+
+-- Recently updated
+project = PROJ AND updated >= -7d
+
+-- Current sprint
+project = PROJ AND sprint in openSprints()
+
+-- Unassigned in backlog
+project = PROJ AND assignee is EMPTY AND status = "To Do"
+```
+
+## CQL Examples (Confluence)
+
+```sql
+-- Pages with title containing "guide"
+title ~ "guide"
+
+-- Pages in specific space
+space = "TEAM" AND type = page
+
+-- Recently modified
+lastModified >= now("-7d")
+
+-- Pages by creator
+creator = currentUser()
+```
+
+## Content Format Options
+
+For Confluence pages, you can specify content format:
+
+- `"markdown"` - Markdown format (easier to read/write)
+- `"adf"` - Atlassian Document Format (native format)
+
+```typescript
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "getConfluencePage"),
+  (arguments =
+    '{"cloudId": "your-site.atlassian.net", "pageId": "123456", "contentFormat": "markdown"}'),
+);
+```
+
+## Transition Workflow
+
+To change issue status, first get available transitions:
+
+```typescript
+// 1. Get available transitions
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "getTransitionsForJiraIssue"),
+  (arguments = '{"cloudId": "your-site.atlassian.net", "issueIdOrKey": "PROJ-123"}'),
+);
+
+// 2. Use transition ID to change status
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "transitionJiraIssue"),
+  (arguments =
+    '{"cloudId": "your-site.atlassian.net", "issueIdOrKey": "PROJ-123", "transition": {"id": "31"}}'),
+);
+```
+
+## Resources
+
+- GitHub: https://github.com/atlassian/atlassian-mcp-server
+- Docs: https://www.atlassian.com/platform/remote-mcp-server
+- Admin Guide: https://support.atlassian.com/security-and-access-policies/docs/understand-atlassian-rovo-mcp-server/

package/dist/template/.opencode/skill/jira/mcp.json

@@ -0,0 +1,6 @@
+{
+	"jira": {
+		"command": "npx",
+		"args": ["-y", "mcp-remote", "https://mcp.atlassian.com/v1/sse"]
+	}
+}

package/dist/template/.opencode/skill/memory-grounding/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: memory-grounding
+description: >
+  Use at the start of any command that needs prior context — searches memory for decisions, patterns, and handoffs before execution to avoid re-solving solved problems.
+version: 1.0.0
+tags: [memory, grounding, pre-flight]
+---
+
+# Memory Grounding
+
+Search institutional memory before executing any command that modifies state or makes decisions.
+
+## When to Use
+
+- At the start of `/ship`, `/plan`, `/create`, `/pr`, `/research`, `/resume`
+- Before any command that benefits from prior context
+- When you need to check if work was already done or decisions already made
+
+## When NOT to Use
+
+- Read-only commands that don't need historical context (e.g., `/status`)
+- Commands that explicitly skip grounding (e.g., `--no-memory` flag)
+
+## Protocol
+
+### Step 1: Search for relevant context
+
+```typescript
+// Primary: search by bead ID or topic
+memory-search({ query: "$ARGUMENTS" });
+
+// Secondary: search by keywords with limit
+memory-search({ query: "<feature or topic keywords>", limit: 5 });
+
+// Optional: filter by type for specific needs
+memory-search({ query: "<keywords>", type: "decision" });  // Past decisions
+memory-search({ query: "<keywords>", type: "bugfix" });    // Known issues
+```
+
+### Step 2: Check last session handoff
+
+```typescript
+memory-read({ file: "handoffs/last" });
+```
+
+### Step 3: Check session history (if resuming work)
+
+```typescript
+find_sessions({ query: "$ARGUMENTS", limit: 3 });
+```
+
+### Step 4: Apply findings
+
+- **If relevant findings exist:** Incorporate them directly. Don't re-solve solved problems.
+- **If prior decisions found:** Follow them unless there's a clear reason to diverge (document the divergence).
+- **If known issues found:** Account for them in the current approach.
+- **If nothing found:** Proceed normally — absence of memory is not a blocker.
+
+## Command-Specific Variations
+
+| Command     | Extra Focus                                            |
+| ----------- | ------------------------------------------------------ |
+| `/plan`     | Search bugfixes; check for existing plans to overwrite |
+| `/ship`     | Search for failed approaches to avoid repeating        |
+| `/create`   | Search for duplicate beads before creating             |
+| `/pr`       | Include findings in PR description                     |
+| `/research` | Search before spawning agents; narrow scope to gaps    |
+| `/resume`   | Read handoff file by bead ID; check session history    |

package/dist/template/.opencode/skill/memory-system/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: memory-system
+description: Use when persisting learnings, loading previous context, or searching past decisions - covers memory file structure, tools, and when to update each file
+version: 1.2.0
+tags: [context, workflow]
+dependencies: []
+---
+
+# Memory System Best Practices
+
+> **Replaces** losing context between sessions — persistent knowledge that survives session boundaries
+
+## When to Use
+
+- Starting work and needing prior decisions, bugfixes, or patterns
+- Recording non-obvious decisions/learnings for future sessions
+- Creating handoffs so the next session can continue quickly
+
+## When NOT to Use
+
+- Ephemeral debugging notes that won't matter after the current task
+- Storing generated artifacts/log dumps as long-term memory
+
+## Core Principle
+
+**Progressive disclosure**: search compactly, fetch fully only when relevant, then record high-signal observations.
+
+## Session Workflow
+
+1. **Ground (search first)**
+   - Run `memory-search` with task keywords before implementation.
+   - Check recent handoffs when resuming interrupted work.
+2. **Calibrate (progressive disclosure)**
+   - Use search results as index.
+   - Fetch full entries only for relevant IDs (`memory-get`).
+   - Pull timeline context only when sequencing matters (`memory-timeline`).
+3. **Record (high-signal only)**
+   - Create `observation` for decisions, bugfixes, patterns, warnings, or durable learnings.
+   - Include searchable concepts and concrete file references.
+4. **Handoff (if session boundary)**
+   - Write a concise status note with completed work, blockers, and next steps using `memory-update` under `handoffs/`.
+
+## What Goes Where
+
+| Store | Put Here | Avoid Here |
+| --- | --- | --- |
+| `observation` (SQLite) | Events: decisions, bugfixes, reusable patterns, warnings | Temporary notes, speculative ideas without evidence |
+| `memory-update` files | Durable docs: handoffs, research, project notes | Every minor runtime detail from a single debug run |
+| Auto pipeline | Captured messages + distillations (automatic) | Manual copying of full transcripts |
+
+## Observation Quality Bar
+
+Use this checklist before creating an observation:
+
+- Is it likely useful in a future session?
+- Is it non-obvious (not already in code/comments)?
+- Can I summarize it in one clear title + short narrative?
+- Did I include strong search terms in `concepts` and relevant files?
+
+If most answers are "no", skip creating the observation.
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Instead |
+| --- | --- | --- |
+| Storing transient debugging info as permanent observations | Pollutes search results with low-value noise | Keep transient info in session context; record only durable findings |
+| Creating observations for every small finding (signal-to-noise) | Important items get buried and retrieval quality drops | Batch minor notes; publish one distilled observation per meaningful outcome |
+| Not searching memory before creating duplicate observations | Produces conflicting/duplicated records | Run `memory-search` first; update/supersede existing records when appropriate |
+| Using `memory-update` for data that should be an observation | Durable events become hard to discover and rank | Use `observation` for events; reserve `memory-update` for document-style files |
+
+## Verification
+
+After creating an observation: `memory-search` with relevant keywords should find it.
+
+## Practical Defaults
+
+- Prefer specific queries over broad ones (`"auth race condition init"` > `"auth"`).
+- For ongoing work, append to one handoff file per task/day instead of many tiny files.
+- Keep observation titles concrete and action-oriented.
+
+## Admin Operations
+
+The `memory-admin` tool supports these operations:
+
+### Core (existing)
+| Operation | Purpose |
+|---|---|
+| `status` | Storage stats, FTS5 health, pipeline counts |
+| `full` | Full maintenance cycle (archive + checkpoint + vacuum) |
+| `archive` | Archive observations older than N days |
+| `checkpoint` | Checkpoint WAL file |
+| `vacuum` | Vacuum database |
+| `migrate` | Import .opencode/memory/observations/*.md into SQLite |
+| `capture-stats` | Temporal message capture statistics |
+| `distill-now` | Force distillation for current session |
+| `curate-now` | Force curator run |
+
+### Knowledge Intelligence (new in v2.1)
+| Operation | Purpose |
+|---|---|
+| `lint` | Find duplicates, contradictions, stale/orphan observations |
+| `index` | Generate a structured catalog of all observations |
+| `compile` | Build concept-grouped articles from observation clusters |
+| `log` | View the append-only operation audit trail |
+
+Examples:
+```
+memory-admin({ operation: "lint" })
+memory-admin({ operation: "lint", older_than_days: 60 })
+memory-admin({ operation: "index" })
+memory-admin({ operation: "compile" })
+memory-admin({ operation: "log" })
+```
+
+### Reading Compiled Artifacts
+```
+memory-read({ file: "index" })             // Full observation catalog
+memory-read({ file: "compiled/auth" })      // Compiled article for "auth" concept
+memory-read({ file: "log" })                // Operation audit trail
+```
+
+## Validation Gate
+
+The `observation` tool now validates before storing:
+- **Exact duplicate** → rejected (returns duplicate ID + supersede hint)
+- **Near-duplicate** → stored with warning
+- **Contradiction** → stored with warning (for decisions sharing concepts)
+- **Low quality** → stored with warning (no narrative + no concepts)
+
+To update an existing observation, use `supersedes`:
+```
+observation({ type: "decision", title: "Use JWT", supersedes: "42", ... })
+```
+
+## Idle Pipeline
+
+During `session.idle`, the memory system automatically runs:
+1. Distill undistilled messages
+2. Curate observations from distillations
+3. Optimize FTS5 index
+4. Checkpoint WAL if large
+5. Compile concept articles (max 10)
+6. Regenerate memory index
+
+## See Also
+
+- `context-management`
+- `session-management`