DOCS_INDEX.md

FastReAct Nano Documentation Index

Last updated: 2026-06-23

This is the maintained documentation center for FastReAct Nano 2.4.2. Current behavior is verified against the codebase; historical reports are linked only through archive indexes.

Quick Start

• Repository README: top-level project entry and service shape.
• Nano README: current backend capabilities, endpoints, and boundaries.
• 5-minute quick start: install, configure, start, and smoke test.
• Short quickstart: compact local run path.
• Configuration file locations: config search order, recommended paths, secrets, PSKA config.

Operations

• Headless service manual: HTTP/SSE endpoints, auth, chat, runs, traces, approvals, policy, MCP diagnostics.
• Deployment: deployment notes.
• Security model: service auth, secrets, policy, approvals, MCP isolation, limits.
• MCP isolation: deeper MCP user isolation guidance.
• Directory structure: current project layout and where generated state belongs.

Architecture

• Architecture: high-level architecture.
• Design: core design.
• Design philosophy: Nano principles.
• System flow: request and execution flow.
• Execution loop audit: ReAct loop review and improvements.
• Frontend/backend audit: service console and backend boundary.

Related current/historical design material:

• OpenClaw research
• FastReAct vs nanobot vs openclaw
• Layer responsibility analysis
• Message routing comparison
• Architecture similarity and migration
• Adapter refactoring plan
• Improvement roadmap

The root docs/ directory is now a pointer only. Maintained docs belong here.

API And Service

• Headless service manual: authoritative endpoint map.
• Agent session API: session API design.
• Agent session API summary: implementation summary.
• PSKA / FastReAct protocol: service boundary and event schema.
• PSKA integration TODO: remaining PSKA integration work.

Current endpoint families:

• Health/readiness: /health, /ready
• Setup/metrics: /v1/setup, /v1/setup/presets, /v1/setup/config-draft, /v1/metrics
• Agent invocation: /v1/chat/completions
• Runs/traces: /v1/runs/*, /v1/traces/*
• Tasks: /v1/tasks/*
• Approvals: /v1/approvals/*
• Policy: /v1/policy, /v1/policy/check
• Tools/skills: /v1/tools, /v1/skills, /v1/skills/diagnostics
• Workspace profile: /v1/workspace/profile

Integrations

• PSKA / FastReAct protocol: PSKA boundary and interop contract.
• Skills and MCP tools: extension model and how skills differ from tools.
• MCP calling mechanism: stdio and HTTP MCP transport behavior.
• How to add skills and MCP: implementation guide.
• Tools and extensions: tool-system notes.
• Dynamic skill selection: skill routing design.

Multi-Tenant And Policy

• Multitenant guide: single/multi-tenant usage guidance.
• Multitenant architecture: architecture implementation guide.
• Multitenant skills/MCP audit: isolation audit.
• Multitenant audit report: broader implementation audit.
• Security model: policy, auth, and approval posture.

When these docs disagree, treat code plus HEADLESS_SERVICE.md and security.md as current. Audit reports may include historical findings.

Development

• Development rules: local development rules.
• Changelog: release history.
• Examples: example programs.
• Scripts: helper scripts.
• Tests: test suite documentation.
• Test coverage goals: coverage notes.
• Release LLM gate: release smoke gate.

Archive

• Repository archive index: pre-nano, v1, migration, sprint, bugfix, and temporary historical docs.
• Nano archive index: nano-era implementation reports, audits, testing reports, and historical analysis.

Archive documents are not current implementation truth. Use them for background and rationale only.

Documentation Inventory Rules

Include:

• README.md
• fastreact-nano/README.md, GETTING_STARTED.md, QUICKSTART.md, CHANGELOG.md, CLAUDE.md
• fastreact-nano/docs/**/*.md
• focused README files under examples/, scripts/, tests/, deploy/, mcp_servers/
• skills/**/SKILL.md when documenting built-in skill behavior

Exclude from maintained documentation inventory:

• node_modules
• .pytest_cache
• MagicMock
• runtime workspace memory/history such as workspaces/*/HISTORY.md, workspaces/*/MEMORY.md, workspaces/*/SOUL.md, workspaces/*/AGENTS.md
• generated logs, test output, coverage output, and temporary reports
• archived files except through archive indexes

Maintenance Rules

• New current docs go under fastreact-nano/docs/.
• Root docs/ stays a pointer only.
• Update existing docs before creating a new one.
• Add short-lived implementation notes to the appropriate archive.
• Update this index whenever adding, moving, or retiring a user-facing doc.
• Validate endpoint claims against src/fastreact/adapters/http.py.
• Validate version claims against pyproject.toml.