Refresh docs, skills, and production runtime assets

.nvmrc

@@ -0,0 +1 @@
+22

AGENTS.md

@@ -0,0 +1,116 @@
+# AFK Repository Guide for Coding Agents
+
+This file is the first stop for LLM agents working in this repository. It summarizes the repo shape, stable commands, and documentation workflow so agentic edits stay grounded in the current codebase.
+
+## Project Snapshot
+
+AFK is a Python 3.13 SDK for building reliable AI agents. The public package imports from `afk.*`; source lives under `src/afk/`.
+
+Core boundaries:
+
+- `afk.agents`: agent definitions, policy, prompts, skills, lifecycle, workflow, A2A.
+- `afk.core`: `Runner`, interaction providers, streaming handles, telemetry contracts.
+- `afk.llms`: provider-portable LLM runtime, adapters, retry/timeout/cache/routing policies.
+- `afk.tools`: typed tools, decorators, registry, sandbox and output limiting.
+- `afk.memory`: memory stores, checkpoints, retention, compaction, vector helpers.
+- `afk.queues`: async task queues, execution contracts, workers, retry/DLQ behavior.
+- `afk.observability`: telemetry collectors, projectors, exporters.
+- `afk.mcp`, `afk.messaging`, `afk.debugger`, `afk.evals`: optional integration and quality layers.
+
+## Ground Rules
+
+- Use public imports in docs and examples, such as `from afk.agents import Agent` and `from afk.core import Runner`.
+- Do not import from `src.afk` or internal module paths in user-facing examples unless the document is explicitly an internals reference.
+- Keep Agent/Runner/Runtime boundaries intact: agents are configuration, runners execute, adapters/tools/memory provide runtime capabilities.
+- Prefer typed contracts: Pydantic models, dataclasses, protocols, and explicit error classes.
+- Add or update docs when changing user-visible behavior, especially runner lifecycle, tools, policy, memory, queues, LLM routing, or env vars.
+- The worktree may contain user changes. Do not revert unrelated edits.
+
+## Common Commands
+
+Install for local development:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install -e . pytest
+```
+
+Run tests:
+
+```bash
+PYTHONPATH=src pytest -q
+```
+
+Run targeted tests:
+
+```bash
+PYTHONPATH=src pytest -q tests/llms/test_llm_settings.py
+PYTHONPATH=src pytest -q tests/queues/test_queue_factory.py
+PYTHONPATH=src pytest -q tests/agents/test_agent_runtime.py
+```
+
+Lint and format when available:
+
+```bash
+ruff check src tests
+ruff format src tests
+```
+
+Preview docs:
+
+```bash
+./scripts/docs_dev.sh
+```
+
+Regenerate agent-friendly docs and skill indexes:
+
+```bash
+./scripts/build_agentic_ai_assets.sh
+```
+
+Install AFK skills with Vercel's Skills CLI:
+
+```bash
+npx skills add https://github.com/arpan404/afk --skill afk-coder
+npx skills add https://github.com/arpan404/afk --skill afk-maintainer
+```
+
+## Documentation Map
+
+- `README.md`: repository landing page and quickest human orientation.
+- `CONTRIBUTING.md`: local setup, tests, PR and docs workflow.
+- `ENV_VARS.md`: environment variable reference grounded in runtime factories/settings.
+- `docs/docs.json`: Mintlify navigation. Add new docs pages here or they are hard to discover.
+- `docs/index.mdx`: public docs landing page.
+- `docs/library/developer-guide.mdx`: framework contributor workflow.
+- `docs/library/building-with-ai.mdx`: application builder playbook.
+- `docs/library/api-reference.mdx`: public import contract.
+- `docs/library/full-module-reference.mdx`: generated/source-level symbol map.
+- `docs/library/examples/index.mdx` and `docs/library/snippets/*.mdx`: runnable examples.
+- `ai-index/`: generated searchable docs records for agents.
+- `skills/afk-coder/`: skill for developers building with AFK.
+- `skills/afk-maintainer/`: skill for maintainers reviewing or changing AFK itself.
+
+## Documentation Quality Checklist
+
+Before finishing docs work:
+
+- New pages are included in `docs/docs.json`.
+- Code examples import `Runner` from `afk.core`, not `afk.agents`.
+- Package install guidance distinguishes distribution install from local editable install.
+- Environment variable names match `src/afk/llms/settings.py`, `src/afk/memory/factory.py`, and `src/afk/queues/factory.py`.
+- Agent-facing docs mention where to search: `python skills/afk-coder/scripts/search_afk_docs.py "query"`.
+- Generated assets are refreshed when navigation, snippets, or skill metadata changes.
+
+## High-Risk Areas
+
+Use extra care and targeted tests when touching:
+
+- `src/afk/core/runner/`: execution loop, checkpoints, resume, policy/failure routing.
+- `src/afk/core/streaming.py`: stream events and handle lifecycle.
+- `src/afk/tools/core/base.py` and `src/afk/tools/registry.py`: tool invocation semantics.
+- `src/afk/tools/security.py`: sandbox, secret scope, output limiting.
+- `src/afk/llms/runtime/`: retries, circuit breakers, rate limits, caching, routing.
+- `src/afk/memory/`: persistence, checkpoint keys, compaction, vector search.
+- `src/afk/queues/`: execution contracts, retry/DLQ, worker lifecycle.
+- `src/afk/agents/a2a/`: auth, delivery guarantees, protocol compatibility.

CONTRIBUTING.md

@@ -40,21 +40,40 @@ PYTHONPATH=src pytest -q tests/agents/test_agent_runtime.py
 - Mintlify config is `docs/docs.json`
 - Main landing page is `docs/index.mdx`
 - AI docs index output is generated under `ai-index/`
-- Coding-agent skills are stored in `agent-skill/`
+- Coding-agent skills are stored in `skills/`
+- Repository instructions for coding agents live in `AGENTS.md`
 
 Local docs preview:
 
 ```bash
-cd docs
-bunx mintlify dev
+./scripts/docs_dev.sh
 ```
 
+Mintlify currently requires an LTS Node runtime and fails on Node 25+. The
+script above runs the preview with Node 22 even if your global `node` points to a
+newer development release.
+
 Build AI-searchable docs index + skill metadata:
 
 ```bash
 ./scripts/build_agentic_ai_assets.sh
 ```
 
+Search the bundled agent docs index:
+
+```bash
+python skills/afk-coder/scripts/search_afk_docs.py "runner resume"
+```
+
+Install the repository skills with Vercel's Skills CLI:
+
+```bash
+npx skills add https://github.com/arpan404/afk --skill afk-coder
+npx skills add https://github.com/arpan404/afk --skill afk-maintainer
+```
+
+Use `afk-coder` when building with AFK. Use `afk-maintainer` when reviewing or changing AFK itself.
+
 ## Contribution Guidelines
 
 - Use public imports (`afk.*`) in examples and docs.

ENV_VARS.md

@@ -1,12 +1,13 @@
-# AFK Python SDK Environment Variables (v1.0.0)
+# AFK Python SDK Environment Variables
 
-This reference documents environment defaults. Runtime configuration APIs remain primary.
+This reference documents environment defaults from the current source. Runtime configuration APIs remain primary.
 
 ## LLM Defaults
 
 | Variable | Default | Description |
 | --- | --- | --- |
 | `AFK_LLM_PROVIDER` | `litellm` | Default provider id (`openai`, `litellm`, `anthropic_agent`) |
+| `AFK_LLM_PROVIDER_ORDER` | _(none)_ | Comma-separated provider preference order |
 | `AFK_LLM_MODEL` | `gpt-4.1-mini` | Default model |
 | `AFK_EMBED_MODEL` | _(none)_ | Embedding model |
 | `AFK_LLM_API_BASE_URL` | _(none)_ | Provider API base |
@@ -23,16 +24,36 @@ This reference documents environment defaults. Runtime configuration APIs remain
 
 | Variable | Default | Description |
 | --- | --- | --- |
-| `AFK_MEMORY_BACKEND` | `sqlite` | `inmemory`, `sqlite`, `redis`, `postgres` |
+| `AFK_MEMORY_BACKEND` | `sqlite` | `memory`, `inmemory`, `sqlite`, `redis`, `postgres` |
 | `AFK_SQLITE_PATH` | `afk_memory.sqlite3` | SQLite file path |
 | `AFK_REDIS_URL` | _(none)_ | Redis URL |
+| `AFK_REDIS_HOST` | `localhost` | Redis host when URL is not set |
+| `AFK_REDIS_PORT` | `6379` | Redis port when URL is not set |
+| `AFK_REDIS_DB` | `0` | Redis DB when URL is not set |
+| `AFK_REDIS_PASSWORD` | _(none)_ | Redis password when URL is not set |
+| `AFK_REDIS_EVENTS_MAX` | `2000` | Max Redis memory events per thread |
 | `AFK_PG_DSN` | _(none)_ | PostgreSQL DSN |
+| `AFK_PG_HOST` | `localhost` | PostgreSQL host when DSN is not set |
+| `AFK_PG_PORT` | `5432` | PostgreSQL port when DSN is not set |
+| `AFK_PG_USER` | `postgres` | PostgreSQL user when DSN is not set |
+| `AFK_PG_PASSWORD` | _(none)_ | PostgreSQL password when DSN is not set |
+| `AFK_PG_DB` | `afk` | PostgreSQL database when DSN is not set |
+| `AFK_PG_SSL` | `false` | Enable PostgreSQL SSL |
+| `AFK_PG_POOL_MIN` | `1` | PostgreSQL pool minimum size |
+| `AFK_PG_POOL_MAX` | `10` | PostgreSQL pool maximum size |
+| `AFK_VECTOR_DIM` | _(required for Postgres)_ | Vector dimension for Postgres memory search |
 
 ## Queue
 
 | Variable | Default | Description |
 | --- | --- | --- |
 | `AFK_QUEUE_BACKEND` | `inmemory` | `inmemory`, `redis` |
+| `AFK_QUEUE_REDIS_URL` | falls back to `AFK_REDIS_URL` | Redis URL for queue backend |
+| `AFK_QUEUE_REDIS_HOST` | falls back to `AFK_REDIS_HOST`, then `localhost` | Redis queue host |
+| `AFK_QUEUE_REDIS_PORT` | falls back to `AFK_REDIS_PORT`, then `6379` | Redis queue port |
+| `AFK_QUEUE_REDIS_DB` | falls back to `AFK_REDIS_DB`, then `0` | Redis queue DB |
+| `AFK_QUEUE_REDIS_PASSWORD` | falls back to `AFK_REDIS_PASSWORD` | Redis queue password |
+| `AFK_QUEUE_REDIS_PREFIX` | `afk:queue` | Redis key prefix |
 | `AFK_QUEUE_RETRY_BACKOFF_BASE_S` | `0.5` | Retry base delay |
 | `AFK_QUEUE_RETRY_BACKOFF_MAX_S` | `30` | Retry max delay |
 | `AFK_QUEUE_RETRY_BACKOFF_JITTER_S` | `0.2` | Retry jitter |
@@ -45,6 +66,29 @@ Execution contracts are configured in code via `TaskWorker(..., execution_contra
 | --- | --- | --- |
 | `AFK_AGENT_PROMPTS_DIR` | `.agents/prompt` | Prompt root directory |
 
+## Runner and Command Tools
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `AFK_ALLOWED_COMMANDS` | _(none)_ | Comma-separated default allowlist for runtime command tools |
+
+## MCP Server
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `AFK_CORS_ORIGINS` | _(none)_ | Comma-separated CORS origins |
+| `AFK_MCP_NAME` | `afk-mcp-server` | Server name |
+| `AFK_MCP_VERSION` | `1.0.0` | Server version |
+| `AFK_MCP_HOST` | `0.0.0.0` | Bind host |
+| `AFK_MCP_PORT` | `8000` | Bind port |
+| `AFK_MCP_INSTRUCTIONS` | _(none)_ | Optional server instructions |
+| `AFK_MCP_PATH` | `/mcp` | HTTP MCP endpoint path |
+| `AFK_MCP_SSE_PATH` | `/mcp/sse` | SSE endpoint path |
+| `AFK_MCP_HEALTH_PATH` | `/health` | Health endpoint path |
+| `AFK_MCP_ENABLE_SSE` | `true` | Enable SSE endpoint |
+| `AFK_MCP_ENABLE_HEALTH` | `true` | Enable health endpoint |
+| `AFK_MCP_ALLOW_BATCH` | `true` | Allow batched MCP requests |
+
 ## A2A
 
 No default environment variables are required. Configure A2A host/auth in code for explicit security posture.