- Create docs/guides/troubleshooting.md: comprehensive troubleshooting
guide covering installation, LLM provider, database, plan execution,
TUI, and test suite issues with step-by-step remediation
- Create docs/guides/faq.md: practical FAQ covering setup, actors,
tools/skills, plans, testing, and contributing
- Create docs/guides/index.md: guides landing page with navigation table
- Expand docs/api/config.md: add complete CLEVERAGENTS_* env var
reference, config file TOML format, actor YAML format, and action
YAML format
- Update mkdocs.yml: add Guides section to site navigation
- docs/api/lsp.md (new): Full API reference for cleveragents.lsp —
LspRegistry, LspRuntime, LspToolAdapter, LspLifecycleManager, LspClient,
LspServerConfig, LspCapability, LspTransport, error types, and actor
YAML integration examples
- docs/api/acms.md (new): API reference for cleveragents.acms —
UKO vocabulary support, Layer 2/3 technology vocabularies (Python,
TypeScript, Rust, Java), DetailLevelMap inheritance, VocabularyRegistry
- docs/api/index.md: Add LSP and ACMS entries to the module index table
- mkdocs.yml: Add LSP Integration and ACMS Vocabularies to API Reference nav
- docs/reference/diagnostics_checks.md: Expand provider API keys table
from 6 to all 9 supported providers (Azure, Cohere, Groq, Together
added) matching implementation in system.py (PR #3469)
Add two new API reference pages:
- docs/api/lsp.md: Full API reference for cleveragents.lsp covering
LspRegistry, LspRuntime, LspLifecycleManager, LspToolAdapter,
LspClient, LspServerConfig, LspCapability, LspTransport, LspBinding,
LanguageDiscovery, and error types.
- docs/api/acms.md: Full API reference for cleveragents.acms covering
UKO vocabulary base types, Layer 2 paradigm vocabularies (OO/Func/Proc),
Layer 3 technology vocabularies (Python/TypeScript/Rust/Java), the
detail level system, and VocabularyRegistry.
Update docs/api/index.md and mkdocs.yml to include both new pages in
the API Reference navigation.
ISSUES CLOSED: #5840
- docs/api/tui.md: Fix Persona dataclass to reflect actual Pydantic model with
all fields (icon, greeting, color, cycle_order, base_arguments, scoped_projects,
scoped_plans). Add PersonaPreset docs and effective_arguments() method.
Add txt export format to /session:export and CLI session export commands.
- docs/api/index.md: Add cleveragents.acms entry linking to reference/acms.md.
- docs/modules/uko-vocabulary-extensions.md: New module guide covering Layer 2
paradigm vocabularies (uko-oo, uko-func, uko-proc) and Layer 3 technology
vocabularies (uko-py, uko-ts, uko-rs, uko-java) with usage examples,
DetailLevelMap inheritance, and VocabularyRegistry API.
- mkdocs.yml: Add Module Guides nav section with shell-safety, uko-provenance,
and uko-vocabulary-extensions pages.
Document changes from PRs merged 2026-04-03 through 2026-04-05:
- CHANGELOG: add entries for CI artifact capture (#2782), ASV provider
benchmarks (#3022), CI quality gate restoration (#2629), plan list
--namespace option (#2616), and MCP 1.4.0 error extraction fix (#2600)
- docs/api/mcp.md: document MCP 1.4.0 error extraction from content[0].text
in MCPToolAdapter.invoke() with protocol note and usage example
- docs/reference/plan_cli.md: add --namespace/-n option to agents plan list
options table, update Filters panel description, add usage examples
- docs/development/ci-cd.md: document CI artifact capture for all 8 nox jobs,
artifact naming convention, retention policy, and agent integration
- docs/api/domain.md: new API reference for cleveragents.domain covering
DomainBaseModel (PR #2014), core domain models, ACMS models, and the
AIProviderInterface protocol
- docs/api/providers.md: new API reference for cleveragents.providers
covering ProviderRegistry, ProviderType, ProviderCapabilities, capability
matrix, default models, and ASV benchmark suite (PR #3022)
- docs/api/index.md: add domain and providers entries to module index
- mkdocs.yml: add Domain Layer and AI Providers pages to nav
- CHANGELOG.md: add [Unreleased] entries for PRs #2616 (plan list
--namespace), #2600 (MCP error extraction), #2629 (CI quality gates),
#3022 (providers benchmarks), #2782 (CI artifacts)
- docs/architecture.md: add CI/Quality Pipeline section documenting
parallel static analysis, pre-migrated DB template, pabot parallel
Robot execution, CI artifacts, and ASV benchmarks
Document the new ShellSafetyService subsystem (DangerousPattern,
ShellDangerLevel, DangerousPatternDetector, SafetyCheckResult) in
docs/api/tui.md with the full built-in pattern table and usage examples.
Update README.md Highlights to surface inline PermissionQuestionWidget,
shell danger detection, and plan workflow isolation (legacy/v3 mixing
guard) introduced in the unreleased milestone.
Added Shell Safety section to docs/api/tui.md documenting the new
cleveragents.tui.shell_safety subsystem introduced in the Unreleased
changelog: ShellDangerLevel, DangerousPattern, DangerousPatternDetector,
ShellSafetyService, and SafetyCheckResult with the full DEFAULT_PATTERNS
table and usage examples.
Created docs/api/domain.md as a new canonical API page for the domain
layer, covering DomainBaseModel (cleveragents.domain.models.base),
ThoughtBlock, InlinePermissionQuestion, PermissionDecision, and
PermissionDecisionEvent, plus a sub-package index for all core domain
models.
Updated docs/api/index.md module table and mkdocs.yml nav to include
the new Domain Models page.
- Add docs/api/action.md: full API reference for ActionConfigSchema and ActionArgumentSchema — field tables, factory methods, camelCase compat mapping, env-var interpolation, database integrity note, and complete YAML example
- Update docs/api/index.md: add cleveragents.action entry to module index
- Update mkdocs.yml: add 'Action Schema: api/action.md' to the API Reference nav
- Update CHANGELOG.md [Unreleased] Fixed: document plan use UNIQUE constraint violation fix (#4174, #4197)
- Clarify from_yaml_file ValueError semantics, document inputs_schema type as dict[str, Any] | None, and update A2A ASV benchmarks to pass method= requests after JSON-RPC migration
ISSUES CLOSED: #7472
Add comprehensive API documentation for the cleveragents.acms package,
covering the four-layer UKO ontology hierarchy (Layer 0-3), all public
types (VocabularyRegistry, ProvenanceInfo, UKOClass, UKOProperty,
UKOVocabulary, Layer2Dependency, ParadigmVocabulary), detail level maps
(DetailLevelMapBuilder, build_detail_level_map, build_effective_map,
resolve_detail_level), and all Layer 3 language vocabulary types for
Python, TypeScript, Rust, and Java.
- Add docs/api/acms.md with full API reference and usage example
- Update docs/api/index.md to include ACMS/UKO in the module index
- Update mkdocs.yml nav to include the new ACMS/UKO page
- Update CHANGELOG.md [Unreleased] with the documentation addition
Add cleveragents.providers to the API Reference module index table.
The providers.md page already exists but was missing from the index,
making it undiscoverable via the documentation navigation.
ISSUES CLOSED: #4940
- docs/api/tui.md: Document ShellDangerLevel, DangerousPattern, DEFAULT_PATTERNS,
DangerousPatternDetector, ShellSafetyService, and SafetyCheckResult with
full API reference, parameter tables, and usage examples
- docs/architecture.md: Add Invariant Reconciliation section covering the
builtin/invariant-reconciliation actor, four-scope algorithm, failure
behaviour, and DI registration
- README.md: Add Invariant Reconciliation, TUI shell danger detection, and
UKO provenance tracking to the Highlights section
ISSUES CLOSED: #3377
- Promote [Unreleased] CHANGELOG entries to [3.8.0] (2026-04-05)
- Add Shell Danger Detection section to docs/api/tui.md covering
ShellDangerLevel, DangerousPattern, ShellSafetyService, and
SafetyCheckResult with full API reference and usage examples
- Add InvariantService section to docs/api/core.md documenting
the new DI-registered singleton, its methods, and emitted events
- Update docs/architecture.md Plan Lifecycle section to document
invariant reconciliation as a phase transition gate
- Update README.md Highlights with shell danger detection, inline
permission questions, invariant reconciliation, UKO provenance
tracking, and JSON-RPC 2.0 A2A wire format
- Create docs/modules/shell-safety.md with full module guide
covering purpose, key classes, built-in patterns, custom pattern
registration, TUI integration, and testing guidance
ISSUES CLOSED: #1003#997#1391#1004#891#1501#1577#1941#2334
- docs/api/providers.md: new comprehensive API reference for
cleveragents.providers — ProviderRegistry, ProviderType,
ProviderCapabilities, ProviderInfo, LangChainChatProvider,
module-level helpers, environment variables, and ASV benchmarks
- docs/api/index.md: add providers module to module index table
- docs/architecture.md: add Provider Registry section with discovery,
selection, and factory usage examples
- CHANGELOG.md: add [Unreleased] entries for:
- agents plan list --namespace/-n option (#2616)
- ASV benchmark suite for providers module (#3022)
- MCP error extraction from content[0].text per MCP 1.4.0 (#2600)
- CI quality gates restored to passing on master (#2629)
Add DomainBaseModel section to docs/api/core.md documenting the shared Pydantic base class from PR #2014 (issue #1941), and add CHANGELOG entry for the CI template DB extension from PR #2399 (issue #2334).
ISSUES CLOSED: #1941
Co-authored-by: Jeffrey Phillips Freeman <jeffrey.freeman@cleverthis.com>
Co-committed-by: Jeffrey Phillips Freeman <jeffrey.freeman@cleverthis.com>
Add PermissionQuestionWidget API documentation to docs/api/tui.md including
method table, key bindings, PermissionDecisionEvent dataclass, and
render_permission_question() helper reference. Add corresponding CHANGELOG
entry under [Unreleased] Added section.
Refs: #997
- CHANGELOG: add [Unreleased] entries for TUI first-run experience (#1391),
session Markdown export (#1004), and UKO provenance/temporal versioning (#891)
- README: add first-run experience and Markdown transcript export bullets
- docs/api/tui.md: new TUI API reference covering first-run, persona system,
input routing, slash commands, session export/import, and widgets
- docs/api/index.md: add TUI entry to module index
- docs/api/resource.md: document DatabaseResourceHandler and DevcontainerHandler
full protocol implementations with method tables and examples
- docs/architecture.md: expand UKO section with provenance/temporal versioning
details; update TUI design decision summary
- mkdocs.yml: add TUI page to API Reference nav
ISSUES CLOSED: #1391#1004#891
Add docs/api/ with per-module API documentation for core, a2a, actor,
skills, tool, mcp, resource, and config packages. Add docs/architecture.md
with a developer-oriented system overview including component map, layer
diagram, plan lifecycle, and key design decisions. Update mkdocs.yml nav
to expose both new sections.
ISSUES CLOSED: #N/A
HAL9000
freemo