Refresh docs, skills, and production runtime assets

.nvmrc

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

AGENTS.md

@@ -0,0 +1,109 @@
+# 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
+```
+
+## 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,31 @@ 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"
+```
+
 ## Contribution Guidelines
 
 - Use public imports (`afk.*`) in examples and docs.

ENV_VARS.md

@@ -23,16 +23,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 |

README.md

@@ -1,4 +1,4 @@
-# Agent Forge Kit (AFK) Python SDK (v1.0.0)
+# Agent Forge Kit (AFK) Python SDK
 
 **A production-grade framework for building robust, deterministic agent systems.**
 
@@ -47,8 +47,16 @@ Choose a raw SDK when you only need simple chat/completions and minimal runtime
 
 ## Installation
 
+Install from the published package when available:
+
+```bash
+pip install afk-py
+```
+
+For repository development, use an editable install:
+
 ```bash
-pip install the-afk==1.0.0
+python -m pip install -e . pytest
 ```
 
 ## Quick Start
@@ -63,7 +71,7 @@ from afk.core import Runner
 # 1. Define your agent (stateless)
 agent = Agent(
     name="ops-bot",
-    model="gpt-4.1-mini",
+    model="gpt-5.2-mini",
     instructions="You are a helpful SRE assistant.",
 )
 
@@ -282,9 +290,14 @@ print(f"Compacted {result.events_compacted} events, "
 
 ## Documentation
 
-- **[Configuration Reference](https://afk.arpan.sh/library/configuration-reference)**: Full list of options.
-- **[API Reference](https://afk.arpan.sh/library/api-reference)**: Classes and methods.
-- **[Architecture & Modules](https://afk.arpan.sh/library/full-module-reference)**: Inner workings.
+- **[Quickstart](https://afk.arpan.sh/library/quickstart)**: Build and run a first agent.
+- **[Developer Guide](https://afk.arpan.sh/library/developer-guide)**: Contribute to AFK itself.
+- **[Building with AI](https://afk.arpan.sh/library/building-with-ai)**: Production patterns for app developers.
+- **[API Reference](https://afk.arpan.sh/library/api-reference)**: Public import contracts.
+- **[Full Module Reference](https://afk.arpan.sh/library/full-module-reference)**: Source-level module map.
+- **[Environment Variables](./ENV_VARS.md)**: Local runtime configuration reference.
+
+For agentic coding work, start with [`AGENTS.md`](./AGENTS.md), then use the bundled skill docs under `skills/`.
 
 ## License
 

docs/docs.json

@@ -16,6 +16,26 @@
     "type": "github",
     "url": "https://github.com/arpan404/afk"
   },
+  "topbarLinks": [
+    {
+      "type": "link",
+      "name": "Quickstart",
+      "url": "/library/quickstart",
+      "arrow": false
+    },
+    {
+      "type": "link",
+      "name": "Examples",
+      "url": "/library/examples/",
+      "arrow": false
+    },
+    {
+      "type": "link",
+      "name": "API",
+      "url": "/library/api-reference",
+      "arrow": false
+    }
+  ],
   "sidebar": {
     "items": "undecorated"
   },
@@ -72,7 +92,11 @@
               "library/agentic-levels",
               "library/architecture",
               "library/building-with-ai",
-              "library/developer-guide"
+              "library/developer-guide",
+              "library/deployment",
+              "library/performance",
+              "library/troubleshooting",
+              "library/migration"
             ]
           },
           {
@@ -138,7 +162,8 @@
           "library/snippets/10_streaming_chat_with_memory",
           "library/snippets/11_cost_monitoring",
           "library/snippets/12_mcp_client_integration",
-          "library/snippets/13_multi_model_fallback"
+          "library/snippets/13_multi_model_fallback",
+          "library/snippets/14_production_client"
         ]
       }
     ]

docs/index.mdx

@@ -164,4 +164,22 @@ flowchart TB
   <Card title="API Reference" icon="book" href="/library/api-reference">
     Complete import reference organized by task.
   </Card>
+  <Card title="Deployment" icon="server" href="/library/deployment">
+    Docker, Kubernetes, and production scaling patterns.
+  </Card>
+  <Card title="Troubleshooting" icon="wrench" href="/library/troubleshooting">
+    Common issues and solutions for AFK agents.
+  </Card>
+  <Card title="Performance" icon="bolt" href="/library/performance">
+    Optimize latency, throughput, and cost.
+  </Card>
+  <Card title="Migration" icon="arrow-right" href="/library/migration">
+    Move from LangChain or OpenAI Assistants API.
+  </Card>
+  <Card title="Architecture" icon="layer-group" href="/library/architecture">
+    System design, component relationships, and design principles.
+  </Card>
+  <Card title="Configuration Reference" icon="gear" href="/library/configuration-reference">
+    All environment variables, config fields, and defaults.
+  </Card>
 </CardGroup>

docs/library/configuration-reference.mdx

@@ -18,7 +18,7 @@ from afk.agents import Agent
 | `model`                     | `str \| LLM`      | **required**     | LLM model name or pre-built client instance                    |
 | `name`                      | `str`             | class name       | Agent identity for logs, telemetry, and subagent routing       |
 | `instructions`              | `str \| callable` | `None`           | System prompt — static string or callable provider             |
-| `instruction_file`          | `str \| Path`     | `None`           | Path to a prompt file (resolved under `prompts_dir`)           |
+| `instruction_file`          | `str \| Path`     | `None`           | Path to a prompt file that must resolve under `prompts_dir`    |
 | `prompts_dir`               | `str \| Path`     | `None`           | Root directory for prompt files (env: `AFK_AGENT_PROMPTS_DIR`) |
 | `tools`                     | `list`            | `[]`             | Typed functions the agent can call                             |
 | `subagents`                 | `list[Agent]`     | `[]`             | Specialist agents this agent can delegate to                   |
@@ -184,8 +184,8 @@ from afk.tools import SandboxProfile
 | -------------------------- | --------------- | --------- | ---------------------------------------------- |
 | `profile_id`               | `str`           | `default` | Profile identifier for logs and policy         |
 | `allow_network`            | `bool`          | `False`   | Whether tools can make network requests        |
-| `allow_command_execution`  | `bool`          | `True`    | Whether tools can execute shell commands       |
-| `allowed_command_prefixes` | `list[str]`     | `[]`      | Allowed command prefixes (empty = all allowed) |
+| `allow_command_execution`  | `bool`          | `False`   | Whether tools can execute shell commands       |
+| `allowed_command_prefixes` | `list[str]`     | `[]`      | Allowed command prefixes (empty = none)        |
 | `deny_shell_operators`     | `bool`          | `True`    | Block pipes, redirects, semicolons             |
 | `allowed_paths`            | `list[str]`     | `[]`      | Restrict file access to these paths            |
 | `denied_paths`             | `list[str]`     | `[]`      | Explicitly deny access to these paths          |