@oneie/claude 0.6.0 → 0.8.0

package/skills/directory-autofill/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: directory-autofill
+description: Fill directory-submission forms in the operator's own Chrome via claude-in-chrome, one queued row at a time, with the human approving every submit. Use whenever an operator says "file with agent", "file these directories", "run the directory autofill", or opens the File-with-agent door on the /u/[slug]/directories board. Never clicks submit, never solves a challenge, always stamps filedBy — see HARD RULES.
+---
+
+# directory-autofill — the browser hand for directory submissions
+
+**Purpose:** Turn a run's queued directory rows into filled, human-approved submissions inside the operator's own logged-in Chrome, using the `claude-in-chrome` MCP tools — `tabs_create_mcp` / `navigate` to open the submit page, `read_page` + `find` to locate inputs, `form_input` to fill them, `computer` for a screenshot (there is no `screenshot` tool; screenshots are a `computer` action). Design + data model: `text/directory-submission-plan.md` § The browser hand. The one page this drives: `/u/[slug]/directories`.
+
+## HARD RULES
+
+- **The human owns the submit.** This skill fills a form and stops. It never clicks the directory's submit button, never confirms a modal that finalizes a listing, and never creates an account on the operator's behalf. The operator reviews the filled form and approves the submit themselves.
+- **Never solves a challenge.** Captcha, email verification, phone verification, or any anti-bot step hands control straight back to the human — this skill does not attempt to defeat them. Resume the loop on the next queued row once the human clears it (or skip and move on).
+- **Provenance always.** Every `POST /api/directories/update` call this skill makes carries `filedBy: "agent"`. If a human takes over mid-fill and finishes the submit themselves, the row is recorded `filedBy: "human"` instead — never claim agent credit for a human-finished row.
+- **One generic matcher, zero per-site scripts.** The `DirectoryField` key set is closed — seven shared templates in `registry.ts` (`F_LOCAL`, `F_REVIEW`, `F_B2B`, `F_STARTUP`, `F_AITOOL`, `F_EMAIL`, `F_VERTICAL`) supply every key, and no directory declares fields inline — and packs are deterministic; the only judgment this skill exercises is "which input on this page is *phone*", via label/placeholder/autocomplete-attribute matching. All 306 directories share this one code path. A site that defeats matching gets filed by hand instead — never write a bespoke per-site scraper.
+- **No stored credentials.** Auth to `/api/directories/*` rides the operator's own session, the same way other operator-side skills call the ONE API (`cc-connect`/do-signal pattern). This skill holds no secrets of its own and never asks for or stores a directory's login.
+- **Watched, paced batches.** Work 10–20 queued rows per sitting, not the whole run unattended — the desktop session is the throttle. Directory sites are exactly the sites with captchas and bot detection; a human present in their own browser dissolves both without evading anything.
+
+## The loop
+
+```
+GET /api/directories/run?slug=<slug>&runId=<runId>
+        │  read the frozen packs for queued rows (batch 10–20)
+        ▼
+open directory.submitUrl in a new Chrome tab
+        ▼
+read the page, match each pack.fields[key] onto the
+  closest form input by label / placeholder / autocomplete
+        ▼
+human checkpoint — the operator reviews the filled
+  form and clicks/approves the actual submit
+        ▼
+capture evidence: confirmation text, listing URL if
+  shown, a screenshot
+        ▼
+POST /api/directories/update
+  { slug, id, status: "submitted", filedBy: "agent" }
+  (and, once the listing appears, a later
+   { status: "live", listingUrl } call — evidence, not
+   assertion, per the status walk)
+        ▼
+next queued row · challenge encountered → hand to the
+  human, resume the loop once cleared (or move on)
+```
+
+## Steps
+
+1. **Get the run.** Ask the operator (or read from the board context) which workspace `slug` and `runId` to work. `GET /api/directories/run?slug=<slug>&runId=<runId>` returns `{ submissions: [{ id, directorySlug, status, pack, listingUrl }] }`, where `pack` is the frozen `{ fields, missing }`. Keep each row's `id` — it is the handle every `update` call needs. Only act on rows with `status: "queued"`.
+2. **Look up the directory.** Cross-reference `directorySlug` against `one.ie/web/src/lib/directories/registry.ts`'s `DIRECTORIES` for the `submitUrl`, `method`, and `fields` list — the pack's `fields` map already carries the values, keyed the same as the registry's `DirectoryField.key`s.
+3. **Open and fill.** Navigate to `submitUrl` in the operator's Chrome. For a `method: 'form'` directory, read the page and match each `pack.fields` entry onto the input whose label/placeholder/autocomplete most plausibly matches that key. The twelve keys the templates can emit: `name`, `company`, `address`, `city`, `phone`, `email`, `website`, `url`, `category`, `tagline`, `description`, `pricing`. For a `method: 'email'` directory, draft the email in the operator's mail client instead of a web form, still stopping before send.
+4. **Stop at the human checkpoint.** Once every matchable field is filled, stop and tell the operator plainly: "Form filled for {directory.name} — review and submit when ready." Do not proceed until the operator confirms they submitted it (or tells you to skip).
+5. **Record the evidence.** After the operator confirms, `POST /api/directories/update` with `{ slug, id, status: "submitted", filedBy: "agent" }`. If the directory's confirmation page shows a live listing URL immediately, follow up once confirmed live with `{ status: "live", listingUrl }` — `listingUrl` is required to mark live, and the route 400s without it. If a listing takes longer to appear, leave the row `submitted` — the operator marks it live later from the board.
+6. **Handle challenges and mismatches.** A captcha, email/phone verification loop, or a form the matcher can't confidently map → stop, tell the operator this row needs a by-hand fill from the pack drawer, and move to the next queued row. Never guess a field mapping you're not confident about — an empty field the operator notices beats a wrong value they don't.
+7. **Repeat, paced.** Work through the batch (10–20 rows), then stop and summarize: how many submitted, how many handed to the human, how many skipped and why.
+
+## Failure modes (designed in, not edge cases)
+
+- **No Chrome session / extension not available** — refuse at startup with a plain message; tell the operator the pack drawer's by-hand path (copy fields, open submit page, mark submitted) is always the fallback.
+- **Field mapping fails** — leave the row `queued`, note which fields couldn't be matched, move on. Never invent a value for a field the pack doesn't supply.
+- **Directory site redesigned / submitUrl dead** — stop and leave the row `queued` with a note saying why. The status walk (`ALLOWED_TRANSITIONS` in `update.ts`) only allows `queued → submitted` and `submitted → live | rejected`, so a queued row **cannot** be marked `rejected` — that call 400s with `invalid_transition`. `rejected` is the verdict on a submission the directory turned down, not on a directory that can't be reached. A note on the stuck row is the signal that routes the registry fix and future runs away from this directory.
+
+## See also
+
+- `text/directory-submission.md` — the promise
+- `text/directory-submission-plan.md` — data model, API shapes, § The browser hand
+- `text/directory-submission-ui.md` — the File-with-agent door on the board
+- `one.ie/web/src/lib/directories/registry.ts` — `DIRECTORIES`, `Directory`, `DirectoryField`
+- `one.ie/web/src/pages/api/directories/run.ts` · `update.ts` — the two guarded routes this skill calls

package/skills/docs/SKILL.md

@@ -9,7 +9,7 @@ This skill is the **middle layer** of three. It does not write prose (that's the
 
 A generic writing skill can make any paragraph clearer. It cannot tell you that the paragraph doesn't belong in a `-reference.md` at all. That judgment is this skill.
 
-**The order:** invoke `docs` (pick type + rules) → copy the matching `template-*.md` (shape) → invoke `writer` (craft the prose) → check `.claude/product-marketing.md` (voice).
+**The order:** invoke `docs` (pick type + rules) → copy the matching `template-*.md` (shape) → invoke `writer` (craft the prose) → invoke `voice` (pick + apply the register) → check `.claude/product-marketing.md` (product context).
 
 The full taxonomy lives in [`text/docs.md`](../../../text/docs.md); the template map in [`text/templates.md`](../../../text/templates.md). This skill is how you *apply* them.
 
@@ -119,9 +119,9 @@ A dense, token-lean briefing for an AI agent that must *act*: the signal chain,
 ## How it composes with the other layers
 
 1. **Pick the type** (this skill) — reader + question → type. If the content spans two types, split before writing.
-2. **Copy the template** — `cp text/template-<type>.md text/<slug>-<suffix>.md`. The template is the shape; never write a doc-spine artifact from scratch.
+2. **Copy the template** — the type → template map is the table in [`text/templates.md`](../../../text/templates.md); most types are `template-<type>.md`, with two exceptions worth knowing before you `cp` the wrong file: the **promise** copies `template-feature.md` (`template-promise.md` is a FOLDED stub — do not copy it) and the **explanation** copies `template-teach.md` (there is no `template-docs.md`). The template is the shape; never write a doc-spine artifact from scratch.
 3. **Write with `writer`** — apply the craft loop (cut, show-don't-tell, structure, sentence polish). This skill says *what goes where*; `writer` makes each sentence land.
-4. **Check voice** — `.claude/product-marketing.md`: ONE's audience (CEOs + engineers), simple English, banned words. Run `do-reconcile.sh dictionary` on the file before committing (no dead names, no new synonyms).
+4. **Check voice** — `.claude/product-marketing.md`: ONE's audience (CEOs + engineers), simple English, banned words. Run `bash .claude/scripts/do-reconcile.sh dictionary text/<file>.md` before committing (no dead names, no new synonyms) — the scripts are not on PATH.
 
 ---
 
@@ -150,4 +150,4 @@ A dense, token-lean briefing for an AI agent that must *act*: the signal chain,
 
 ---
 
-*Taxonomy: [`text/docs.md`](../../../text/docs.md). Templates: [`text/templates.md`](../../../text/templates.md). Craft: `writer` skill. Voice: [`.claude/product-marketing.md`](../../product-marketing.md).*
+*Taxonomy: [`text/docs.md`](../../../text/docs.md). Templates: [`text/templates.md`](../../../text/templates.md). Craft: `writer` skill. Register: `voice` skill → [`text/voice-and-tone.md`](../../../text/voice-and-tone.md) (senior) + [`text/writing-style-guide.md`](../../../text/writing-style-guide.md). Product context: [`.claude/product-marketing.md`](../../product-marketing.md).*

package/skills/livekit-agents/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: livekit-agents
+description: 'Build voice AI agents with LiveKit Cloud and the Agents SDK. Use when the user asks to "build a voice agent", "create a LiveKit agent", "add voice AI", "implement handoffs", "structure agent workflows", or is working with LiveKit Agents SDK. Provides opinionated guidance for the recommended path: LiveKit Cloud + LiveKit Inference. REQUIRES writing tests for all implementations.'
+license: MIT
+metadata:
+  author: livekit
+  version: "0.3.1"
+---
+
+# LiveKit Agents Development for LiveKit Cloud
+
+This skill provides opinionated guidance for building voice AI agents with LiveKit Cloud. It assumes you are using LiveKit Cloud (the recommended path) and encodes *how to approach* agent development, not API specifics. All factual information about APIs, methods, and configurations must come from live documentation.
+
+**This skill is for LiveKit Cloud developers.** If you're self-hosting LiveKit, some recommendations (particularly around LiveKit Inference) won't apply directly.
+
+## MANDATORY: Read This Checklist Before Starting
+
+Before writing ANY code, complete this checklist:
+
+1. **Read this entire skill document** - Do not skip sections even if MCP is available
+2. **Ensure LiveKit Cloud project is connected** - You need `LIVEKIT_URL`, `LIVEKIT_API_KEY`, and `LIVEKIT_API_SECRET` from your Cloud project
+3. **Set up documentation access** - Use MCP if available, otherwise use web search
+4. **Plan to write tests** - Every agent implementation MUST include tests (see testing section below)
+5. **Verify all APIs against live docs** - Never rely on model memory for LiveKit APIs
+
+This checklist applies regardless of whether MCP is available. MCP provides documentation access but does NOT replace the guidance in this skill.
+
+## LiveKit Cloud Setup
+
+LiveKit Cloud is the fastest way to get a voice agent running. It provides:
+- Managed infrastructure (no servers to deploy)
+- **LiveKit Inference** for AI models (no separate API keys needed)
+- Built-in noise cancellation, turn detection, and other voice features
+- Simple credential management
+
+### Connect to Your Cloud Project
+
+1. Sign up at [cloud.livekit.io](https://cloud.livekit.io) if you haven't already
+2. Create a project (or use an existing one)
+3. Get your credentials from the project settings:
+   - `LIVEKIT_URL` - Your project's WebSocket URL (e.g., `wss://your-project.livekit.cloud`)
+   - `LIVEKIT_API_KEY` - API key for authentication
+   - `LIVEKIT_API_SECRET` - API secret for authentication
+
+4. Set these as environment variables (typically in `.env.local`):
+```bash
+LIVEKIT_URL=wss://your-project.livekit.cloud
+LIVEKIT_API_KEY=your-api-key
+LIVEKIT_API_SECRET=your-api-secret
+```
+
+The LiveKit CLI can automate credential setup. Consult the CLI documentation for current commands.
+
+### Use LiveKit Inference for AI Models
+
+**LiveKit Inference is the recommended way to use AI models with LiveKit Cloud.** It provides access to leading AI model providers—all through your LiveKit credentials with no separate API keys needed.
+
+Benefits of LiveKit Inference:
+- No separate API keys to manage for each AI provider
+- Billing consolidated through your LiveKit Cloud account
+- Optimized for voice AI workloads
+
+Consult the documentation for available models, supported providers, and current usage patterns. The documentation always has the most up-to-date information.
+
+## Critical Rule: Never Trust Model Memory for LiveKit APIs
+
+LiveKit Agents is a fast-evolving SDK. Model training data is outdated the moment it's created. When working with LiveKit:
+
+- **Never assume** API signatures, method names, or configuration options from memory
+- **Never guess** SDK behavior or default values
+- **Always verify** against live documentation before writing code
+- **Always cite** the documentation source when implementing features
+
+This rule applies even when confident about an API. Verify anyway.
+
+## REQUIRED: Use LiveKit MCP Server for Documentation
+
+Before writing any LiveKit code, ensure access to the LiveKit documentation MCP server. This provides current, verified API information and prevents reliance on stale model knowledge.
+
+### Check for MCP Availability
+
+Look for `livekit-docs` MCP tools. If available, use them for all documentation lookups:
+- Search documentation before implementing any feature
+- Verify API signatures and method parameters
+- Look up configuration options and their valid values
+- Find working examples for the specific task at hand
+
+### If MCP Is Not Available
+
+If the LiveKit MCP server is not configured, inform the user and recommend installation. Installation instructions for all supported platforms are available at:
+
+**https://docs.livekit.io/intro/mcp-server/**
+
+Fetch the installation instructions appropriate for the user's coding agent from that page.
+
+### Fallback When MCP Unavailable
+
+If MCP cannot be installed in the current session:
+1. **Inform the user immediately** that documentation cannot be verified in real-time
+2. Use web search to fetch current documentation from docs.livekit.io
+3. **Explicitly mark all LiveKit-specific code** with a comment like `# UNVERIFIED: Please check docs.livekit.io for current API`
+4. **State clearly** when you cannot verify something: "I cannot verify this API signature against current documentation"
+5. Recommend the user verify against https://docs.livekit.io before using the code
+
+## Voice Agent Architecture Principles
+
+Voice AI agents have fundamentally different requirements than text-based agents or traditional software. Internalize these principles:
+
+### Latency Is Critical
+
+Voice conversations are real-time. Users expect responses within hundreds of milliseconds, not seconds. Every architectural decision should consider latency impact:
+
+- Minimize LLM context size to reduce inference time
+- Avoid unnecessary tool calls during active conversation
+- Prefer streaming responses over batch responses
+- Design for the unhappy path (network delays, API timeouts)
+
+### Context Bloat Kills Performance
+
+Large system prompts and extensive tool lists directly increase latency. A voice agent with 50 tools and a 10,000-token system prompt will feel sluggish regardless of model speed.
+
+Design agents with minimal viable context:
+- Include only tools relevant to the current conversation phase
+- Keep system prompts focused and concise
+- Remove tools and context that aren't actively needed
+
+### Users Don't Read, They Listen
+
+Voice interface constraints differ from text:
+- Long responses frustrate users—keep outputs concise
+- Users cannot scroll back—ensure clarity on first delivery
+- Interruptions are normal—design for graceful handling
+- Silence feels broken—acknowledge processing when needed
+
+## Workflow Architecture: Handoffs and Tasks
+
+Complex voice agents should not be monolithic. LiveKit Agents supports structured workflows that maintain low latency while handling sophisticated use cases.
+
+### The Problem with Monolithic Agents
+
+A single agent handling an entire conversation flow accumulates:
+- Tools for every possible action (bloated tool list)
+- Instructions for every conversation phase (bloated context)
+- State management for all scenarios (complexity)
+
+This creates latency and reduces reliability.
+
+### Handoffs: Agent-to-Agent Transitions
+
+Handoffs allow one agent to transfer control to another. Use handoffs to:
+- Separate distinct conversation phases (greeting → intake → resolution)
+- Isolate specialized capabilities (general support → billing specialist)
+- Manage context boundaries (each agent has only what it needs)
+
+Design handoffs around natural conversation boundaries where context can be summarized rather than transferred wholesale.
+
+### Tasks: Scoped Operations
+
+Tasks are tightly-scoped prompts designed to achieve a specific outcome. Use tasks for:
+- Discrete operations that don't require full agent capabilities
+- Situations where a focused prompt outperforms a general-purpose agent
+- Reducing context when only a specific capability is needed
+
+Consult the documentation for implementation details on handoffs and tasks.
+
+## REQUIRED: Write Tests for Agent Behavior
+
+Voice agent behavior is code. Every agent implementation MUST include tests. Shipping an agent without tests is shipping untested code.
+
+### Mandatory Testing Workflow
+
+When building or modifying a LiveKit agent:
+
+1. **Create a `tests/` directory** if one doesn't exist
+2. **Write at least one test** before considering the implementation complete
+3. **Test the core behavior** the user requested
+4. **Run the tests** to verify they pass
+
+### Test-Driven Development Process
+
+When modifying agent behavior—instructions, tool descriptions, workflows—begin by writing tests for the desired behavior:
+
+1. Define what the agent should do in specific scenarios
+2. Write test cases that verify this behavior
+3. Implement the feature
+4. Iterate until tests pass
+
+This approach prevents shipping agents that "seem to work" but fail in production.
+
+### What Every Agent Test Should Cover
+
+At minimum, write tests for:
+- **Basic conversation flow**: Agent responds appropriately to a greeting
+- **Tool invocation** (if tools exist): Tools are called with correct parameters
+- **Error handling**: Agent handles unexpected input gracefully
+
+Focus tests on:
+- **Tool invocation**: Does the agent call the right tools with correct parameters?
+- **Response quality**: Does the agent produce appropriate responses for given inputs?
+- **Workflow transitions**: Do handoffs and tasks trigger correctly?
+- **Edge cases**: How does the agent handle unexpected input, interruptions, silence?
+
+### Test Implementation Pattern
+
+Use LiveKit's testing framework. Consult the testing documentation via MCP for current patterns:
+```
+search: "livekit agents testing"
+```
+
+The framework supports:
+- Simulated user input
+- Verification of agent responses
+- Tool call assertions
+- Workflow transition testing
+
+### Why This Is Non-Negotiable
+
+Agents that "seem to work" in manual testing frequently fail in production:
+- Prompt changes silently break behavior
+- Tool descriptions affect when tools are called
+- Model updates change response patterns
+
+Tests catch these issues before users do.
+
+### Skipping Tests
+
+If a user explicitly requests no tests, proceed without them but inform them:
+> "I've built the agent without tests as requested. I strongly recommend adding tests before deploying to production. Voice agents are difficult to verify manually and tests prevent silent regressions."
+
+## Common Mistakes to Avoid
+
+### Overloading the Initial Agent
+
+Starting with one agent that "does everything" and adding tools/instructions over time. Instead, design workflow structure upfront, even if initial implementation is simple.
+
+### Ignoring Latency Until It's a Problem
+
+Latency issues compound. An agent that feels "a bit slow" in development becomes unusable in production with real network conditions. Measure and optimize latency continuously.
+
+### Copying Examples Without Understanding
+
+Examples in documentation demonstrate specific patterns. Copying code without understanding its purpose leads to bloated, poorly-structured agents. Understand what each component does before including it.
+
+### Skipping Tests Because "It's Just Prompts"
+
+Agent behavior is code. Prompt changes affect behavior as much as code changes. Test agent behavior with the same rigor as traditional software. **Never deliver an agent implementation without at least one test file.**
+
+### Assuming Model Knowledge Is Current
+
+Reiterating the critical rule: never trust model memory for LiveKit APIs. The SDK evolves faster than model training cycles. Verify everything.
+
+## When to Consult Documentation
+
+**Always consult documentation for:**
+- API method signatures and parameters
+- Configuration options and their valid values
+- SDK version-specific features or changes
+- Deployment and infrastructure setup
+- Model provider integration details
+- CLI commands and flags
+
+**This skill provides guidance on:**
+- Architectural approach and design principles
+- Workflow structure decisions
+- Testing strategy
+- Common pitfalls to avoid
+
+The distinction matters: this skill tells you *how to think* about building voice agents. The documentation tells you *how to implement* specific features.
+
+## Feedback Loop
+
+When using LiveKit documentation via MCP, note any gaps, outdated information, or confusing content. Reporting documentation issues helps improve the ecosystem for all developers.
+
+## Summary
+
+Building effective voice agents with LiveKit Cloud requires:
+
+1. **Use LiveKit Cloud + LiveKit Inference** as the foundation—it's the fastest path to production
+2. **Verify everything** against live documentation—never trust model memory
+3. **Minimize latency** at every architectural decision point
+4. **Structure workflows** using handoffs and tasks to manage complexity
+5. **Test behavior** before and after changes—never ship without tests
+6. **Keep context minimal**—only include what's needed for the current phase
+
+These principles remain valid regardless of SDK version or API changes. For all implementation specifics, consult the LiveKit documentation via MCP.

package/skills/livekit-agents/references/freshness-rules.md

@@ -0,0 +1,168 @@
+# Freshness Rules for LiveKit Development
+
+This document provides detailed guidance on maintaining accuracy when building with LiveKit Agents. These rules exist because model training data becomes outdated immediately, and LiveKit's SDK evolves rapidly.
+
+## The Core Problem
+
+Coding agents (Claude, GPT, etc.) are trained on historical data. This training includes:
+- Old versions of LiveKit documentation
+- Outdated code examples from blogs and tutorials
+- Previous SDK versions with different APIs
+- Community answers that may no longer be accurate
+
+When an agent "knows" something about LiveKit, that knowledge may be months or years out of date.
+
+## Verification Requirements
+
+### Before Writing Any LiveKit Code
+
+1. **Identify what needs verification**
+   - Method names and signatures
+   - Configuration options and their types
+   - Import paths and module structure
+   - Default values and behaviors
+
+2. **Query the documentation**
+   - Use MCP to search for the specific feature
+   - Read the current documentation, not cached knowledge
+   - Look for version notes or recent changes
+
+3. **Cite your source**
+   - Note which documentation page informed the implementation
+   - If something cannot be verified, explicitly state this
+
+### During Implementation
+
+When writing code, verify:
+
+| Element | Why It Changes | How to Verify |
+|---------|----------------|---------------|
+| Import statements | Module restructuring | Search docs for current import paths |
+| Method signatures | API evolution | Look up method in API reference |
+| Configuration keys | Naming conventions change | Check configuration documentation |
+| Default behaviors | Defaults are tuned over time | Read parameter documentation |
+| Event names | Event systems evolve | Check events/callbacks documentation |
+
+### After Implementation
+
+Before presenting code to the user:
+- Confirm all APIs used are documented
+- Verify example patterns match current best practices
+- Check for deprecation warnings in documentation
+
+## What Cannot Be Verified
+
+Some things legitimately cannot be verified against documentation:
+- User's specific environment or configuration
+- Integration with user's existing codebase
+- Business logic and application requirements
+
+When providing guidance on these topics, clearly distinguish between:
+- "According to LiveKit documentation..." (verified)
+- "Based on your requirements..." (application-specific)
+- "This may need adjustment..." (uncertain)
+
+## Red Flags: When to Stop and Verify
+
+Pause and verify against documentation when:
+
+1. **Writing from memory** - If you're typing an API call without having just looked it up, verify it
+2. **"I think" or "I believe"** - Uncertainty about LiveKit APIs requires verification
+3. **Complex configurations** - Multi-option configurations are likely to have evolved
+4. **Error handling** - Exception types and error formats change
+5. **Newer features** - Recently added features have the highest drift risk
+
+## Communication with Users
+
+### When Verified
+
+```
+According to the LiveKit Agents documentation, the correct approach is...
+[implementation]
+```
+
+### When Partially Verified
+
+```
+The workflow structure follows LiveKit's documented patterns. However, I could not
+verify [specific detail] against current documentation. Please confirm this matches
+your SDK version.
+```
+
+### When Unverified
+
+```
+I cannot verify this implementation against current LiveKit documentation. This is
+based on general patterns and may require adjustment. I recommend:
+1. Checking the official documentation at [link]
+2. Testing this implementation before relying on it
+```
+
+## MCP Server Unavailable
+
+If the LiveKit MCP server is not installed or accessible:
+
+1. **Inform the user immediately** - They should know verification isn't possible
+2. **Recommend installation** - Point to https://docs.livekit.io/mcp
+3. **Proceed with caution** - Clearly mark all LiveKit-specific code as unverified
+4. **Suggest manual verification** - User should check docs before using the code
+
+Do not pretend to have verified something when MCP access was unavailable.
+
+## Version Awareness
+
+LiveKit Agents has distinct versions with potentially different APIs:
+- Python SDK (`livekit-agents`)
+- Node.js/TypeScript SDK (`@livekit/agents`)
+
+Each has its own release cycle and API surface. When working with LiveKit:
+- Determine which SDK the user is using
+- Search documentation specific to that SDK
+- Do not assume API parity between Python and Node.js versions
+
+## Examples of Drift
+
+These examples illustrate why verification matters:
+
+### Configuration Changes
+Old tutorials might show:
+```python
+agent = VoiceAgent(config={"model": "gpt-4"})
+```
+
+Current API might be:
+```python
+agent = VoiceAgent(llm=SomeLLMClass(...))
+```
+
+### Method Renames
+What was once:
+```python
+agent.start_session()
+```
+
+Might now be:
+```python
+agent.start()
+```
+
+### Import Restructuring
+Previous:
+```python
+from livekit.agents.voice import VoiceAgent
+```
+
+Current:
+```python
+from livekit.agents import VoiceAgent
+```
+
+None of these changes are predictable from training data. Only live documentation reflects current state.
+
+## Summary
+
+1. **Default to distrust** - Assume any LiveKit knowledge from memory is outdated
+2. **Verify actively** - Use MCP to check documentation before implementation
+3. **Communicate uncertainty** - Tell users when something cannot be verified
+4. **Cite sources** - Reference documentation when providing verified information
+5. **Recommend MCP** - If unavailable, make installation a priority