docs: add CHANGELOG.md and CONTRIBUTING.md to docs tree

Add docs/CHANGELOG.md as a documentation-tree mirror of the root
CHANGELOG.md, covering version history from v3.0.0 through v3.8.0
with links back to the authoritative root file.

Add docs/CONTRIBUTING.md as a quick-start documentation-tree mirror
of the root CONTRIBUTING.md, covering development setup, testing
instructions, code style guidelines, and the PR submission process.

Update mkdocs.yml nav to include both new pages (Changelog and
Contributing) between the FAQ and Reference sections.

docs/CHANGELOG.md

@@ -0,0 +1,153 @@
+# Changelog (Documentation)
+
+> **Note:** This file is the documentation-tree mirror of the project changelog.
+> The authoritative source is the [root CHANGELOG.md](../CHANGELOG.md) at the
+> repository root. This page is rendered as part of the MkDocs site for
+> convenient in-docs browsing.
+
+---
+
+## [3.8.0] — 2026-04-05
+
+### Added
+
+- Wired Invariant Reconciliation Actor auto-invocation into `PlanLifecycleService`
+  phase transitions (`start_strategize`, `execute_plan`, `apply_plan`). Reconciliation
+  failures now block the transition with `ReconciliationBlockedError` and emit
+  `INVARIANT_VIOLATED` events.
+- **TUI — Shell danger detection**: The TUI shell mode (`!` prefix) now detects dangerous
+  command patterns before execution. A configurable pattern registry classifies commands by
+  danger level (warning, critical) and surfaces a user warning overlay before proceeding.
+- **TUI — Permission Question Widget**: A new inline `PermissionQuestionWidget` renders
+  permission requests directly in the conversation stream for single-file operations.
+- **TUI — Actor thought blocks**: Expandable reasoning trace widgets rendered inline in the
+  conversation stream with muted styling. Collapsed by default; expand with `Space` or click.
+- **UKO provenance tracking**: Every typed triple now carries `sourceResource`, `validFrom`,
+  and `isCurrent` metadata. A revision chain enables temporal queries and point-in-time
+  ontology state reconstruction.
+- **JSON-RPC 2.0 A2A wire format**: `A2aRequest`/`A2aResponse` fields renamed to standard
+  JSON-RPC 2.0 names (`method`, `id`, `result`, `error`).
+- **Database resource handler**: Full CRUD and checkpoint/rollback support for SQLite,
+  PostgreSQL, MySQL, and DuckDB resources via the resource DAG.
+- **Estimation lifecycle hook**: `actor.default.estimation` config key wires an estimation
+  actor into the Strategize-to-Estimate lifecycle hook.
+- **Persona system**: YAML-backed personas bind actors, argument presets, and scope references
+  to named identities; persisted in `~/.config/cleveragents/personas/`.
+- **Session management**: Create, list, export, and import conversation sessions; full JSON
+  export/import for portability; Markdown transcript export (`--format md`).
+- **Server mode**: `agents server connect` configures a remote CleverAgents server; Kubernetes
+  Helm chart in `k8s/` for production deployment.
+- **Invariant reconciliation**: `InvariantReconciliationActor` runs automatically at every plan
+  phase transition; failures block the transition and emit `INVARIANT_VIOLATED`.
+- **UKO runtime**: Universal Knowledge Ontology query interface, inference engine, and graph
+  persistence for ACMS context strategies.
+
+---
+
+## [3.7.0] — 2026-03-15
+
+### Added
+
+- **Interactive TUI** (`agents tui`) — full-screen Textual app with multi-session tabs, persona
+  switching, slash commands (67 commands across 14 groups), reference picker (`@`), shell mode
+  (`!`), context-sensitive F1 help, and `Ctrl+T` argument preset cycling.
+- **Slash command system** — 67 commands across 14 groups accessible via `/` overlay.
+- **Reference picker** — `@` key opens a file/resource reference picker that inserts references
+  into the input field.
+- **TUI persona system** — YAML-backed personas bind actors, argument presets, and scope
+  references; persisted in `~/.config/cleveragents/personas/`.
+- **TUI session export/import** — full JSON round-trip and Markdown transcript export
+  (`--format md`).
+
+---
+
+## [3.6.0] — 2026-02-28
+
+### Added
+
+- Advanced Context Management System (ACMS) with three-tier context strategy.
+- UKO Runtime (Universal Knowledge Ontology) with graph persistence and inference engine.
+- Implicit inference engine producing `uko:implicitSiblingOf`, `uko:implicitContains`, and
+  `uko:implicitDependsOn` triples with confidence 0.7.
+
+---
+
+## [3.5.0] — 2026-02-14
+
+### Added
+
+- Autonomy hardening: advisory locking, validation pipeline, definition-of-done gating.
+- Resource DAG with dependency tracking and type hierarchy with multiple inheritance.
+- Container resource types (`container.docker`, `container.podman`).
+- LSP resource types (`lsp.*`).
+
+---
+
+## [3.4.0] — 2026-01-31
+
+### Added
+
+- ACMS v1 with context scaling strategies.
+- Resource type inheritance system (ADR-042).
+- Safety profile extraction (ADR-041).
+
+---
+
+## [3.3.0] — 2026-01-17
+
+### Added
+
+- Corrections and subplans support in plan lifecycle.
+- Checkpoint and rollback for all resource writes.
+- Decision tree versioning and history (ADR-034).
+- Decision tree rollback and replay (ADR-035).
+
+---
+
+## [3.2.0] — 2026-01-03
+
+### Added
+
+- Decisions, validations, and invariants in plan lifecycle.
+- Validation abstraction layer (ADR-013).
+- Invariant system (ADR-016).
+- Automation profiles (ADR-017).
+- Semantic error prevention (ADR-018).
+
+---
+
+## [3.1.0] — 2025-12-20
+
+### Added
+
+- MCP (Model Context Protocol) adapter and client (ADR-029).
+- LSP (Language Server Protocol) client integration (ADR-027).
+- Agent Skills Standard (AgentSkills.io) support (ADR-028).
+- Skill abstraction definition (ADR-030).
+
+---
+
+## [3.0.0] — 2025-12-06
+
+### Added
+
+- Initial public release of CleverAgents Core.
+- Unified `agents` / `cleveragents` CLI entry points.
+- Layered architecture: Entry Points → Application → Domain → Infrastructure → Integration → Core.
+- Actor system with YAML-defined LangGraph node graphs.
+- Tool system with four-stage lifecycle (activate → validate → execute → deactivate).
+- Skill system with three-tier progressive disclosure.
+- Resource system with DAG and type hierarchy.
+- A2A (Agent-to-Agent) protocol facade.
+- DI container (`cleveragents.application.container`).
+- LangChain/LangGraph integration (ADR-022).
+- Provider registry with fallback chain (OpenAI → Anthropic → Google → Azure → OpenRouter → Groq → Together → Cohere).
+- Observability: structured logging, metrics, audit trail, token/cost tracking.
+- BDD test suite (Behave + Robot Framework).
+- Nox automation for lint, typecheck, tests, docs, benchmarks.
+- MkDocs-powered documentation with CleverAgents branding.
+
+---
+
+*For the complete changelog including unreleased changes and detailed fix notes, see the
+[root CHANGELOG.md](../CHANGELOG.md).*

docs/CONTRIBUTING.md

@@ -0,0 +1,157 @@
+# Contributing to CleverAgents Core (Documentation)
+
+> **Note:** This page is the documentation-tree mirror of the project contributing guide.
+> The authoritative source is the [root CONTRIBUTING.md](../CONTRIBUTING.md) at the
+> repository root. This page provides a quick-start summary for contributors browsing
+> the MkDocs site.
+
+---
+
+## Quick Start
+
+1. **Fork** the repository on Forgejo and clone your fork locally.
+2. **Create a branch** following the naming convention:
+   - Features: `feature/mN-short-description`
+   - Bug fixes: `bugfix/mN-short-description`
+   - TDD tests: `tdd/mN-short-description`
+   - Documentation: `docs/short-description`
+3. **Make your changes**, following the guidelines below.
+4. **Run the full test suite** with `nox` before submitting.
+5. **Open a Pull Request** targeting `master`.
+
+---
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.11+
+- [uv](https://github.com/astral-sh/uv) package manager
+- [nox](https://nox.thea.codes/) for task automation
+- [pre-commit](https://pre-commit.com/) for commit hooks
+
+### Initial Setup
+
+```bash
+# Clone the repository
+git clone https://git.cleverthis.com/cleveragents/cleveragents-core.git
+cd cleveragents-core
+
+# Install dependencies and set up pre-commit hooks
+scripts/setup-dev.sh
+```
+
+The `setup-dev.sh` script will:
+
+- Create a virtual environment with `uv`
+- Install all development dependencies
+- Configure pre-commit hooks (lint, format, typecheck, commit-msg validation)
+
+---
+
+## Testing Instructions
+
+All tests are run via `nox`. **Do not invoke `behave`, `robot`, or pytest directly.**
+
+| Command | Purpose |
+|---------|---------|
+| `nox` | Full suite: lint, typecheck, security, unit tests, integration tests, coverage |
+| `nox -s unit_tests` | Behave BDD unit tests only |
+| `nox -s integration_tests` | Robot Framework integration tests only |
+| `nox -s coverage_report` | Coverage report (must stay ≥ 97%) |
+| `nox -s lint` | Ruff linting |
+| `nox -s typecheck` | Pyright strict type checking |
+| `nox -s benchmark` | ASV performance benchmarks |
+
+### Test Framework Conventions
+
+- **Unit tests** use [Behave](https://behave.readthedocs.io/) (BDD/Gherkin) under `features/`.
+- **Integration and end-to-end tests** use [Robot Framework](https://robotframework.org/) under `robot/`.
+- **No pytest-style tests** — there is intentionally no `tests/` directory.
+- **Mocks** belong exclusively under `features/mocks/`. Never place mock code in `src/`.
+
+### Coverage Requirement
+
+Unit test coverage must remain **above 97%** at all times. This is enforced as a CI merge gate.
+
+---
+
+## Code Style Guidelines
+
+### Python
+
+- **Formatter**: [Ruff](https://docs.astral.sh/ruff/) (configured in `pyproject.toml`)
+- **Linter**: Ruff
+- **Type checker**: [Pyright](https://github.com/microsoft/pyright) in strict mode
+- All code must pass `nox -s typecheck` — never use `# type: ignore` comments.
+- Imports must be at the top of each file; no scattered or conditional imports
+  (exception: `if TYPE_CHECKING:` blocks for circular-import avoidance only).
+- Prefer `from module import ClassName` over `import module` when only a few names are used.
+
+### File Organization
+
+| Directory | Contents |
+|-----------|---------|
+| `src/cleveragents/` | Production source code only — no tests, mocks, or examples |
+| `features/` | Behave BDD tests and mocks (`features/mocks/`) |
+| `robot/` | Robot Framework integration and e2e tests |
+| `docs/` | MkDocs documentation (Markdown) |
+| `scripts/` | Utility scripts |
+| `examples/` | Example code |
+| `k8s/` | Kubernetes Helm chart |
+
+### Commit Messages
+
+Commit messages must follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<scope>): <short summary>
+
+<optional body>
+```
+
+Valid types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `perf`, `ci`.
+
+The first line of the commit message must match the **Commit Message** field in the issue
+metadata exactly. This is enforced by the pre-commit `commit-msg` hook via Commitizen.
+
+---
+
+## Pull Request Submission Process
+
+### Before Opening a PR
+
+1. Ensure `nox` passes with no failures.
+2. Ensure coverage is ≥ 97% (`nox -s coverage_report`).
+3. Ensure all pre-commit hooks pass (`pre-commit run --all-files`).
+4. Rebase your branch on the latest `master`.
+
+### PR Requirements
+
+- **Title**: Must match the issue's Commit Message metadata field.
+- **Body**: Must reference the issue with `Closes #<issue_number>`.
+- **Branch protection**: The `status-check` CI gate must pass (lint, typecheck, security,
+  unit_tests, coverage).
+- **Review**: At least 1 approval required. Self-approval is permitted for automated PRs.
+
+### Bug Fix Workflow (TDD)
+
+All bug fixes follow a mandatory TDD workflow:
+
+1. A `Type/Testing` issue is created with a failing test tagged `@tdd_issue @tdd_issue_<N> @tdd_expected_fail`.
+2. The TDD PR is merged to `master` first (test passes CI via result inversion).
+3. The bug fix PR removes `@tdd_expected_fail` and implements the fix.
+4. CI enforces that `@tdd_expected_fail` is removed when the fix PR closes the bug issue.
+
+See the [root CONTRIBUTING.md](../CONTRIBUTING.md) for the complete workflow, label system,
+ticket lifecycle, and project-specific guidelines.
+
+---
+
+## Additional Resources
+
+- [Architecture Overview](architecture.md)
+- [Specification](specification.md)
+- [Development Guides](development/testing.md)
+- [CI/CD Pipeline](development/ci-cd.md)
+- [ADR Index](adr/index.md)

mkdocs.yml

@@ -44,6 +44,8 @@ nav:
     - Documentation Writer: development/docs-writer.md
   - Implementation Timeline: timeline.md
   - FAQ: faq.md
+  - Changelog: CHANGELOG.md
+  - Contributing: CONTRIBUTING.md
   - Reference: reference/
   - Architecture Decision Records (ADRs):
     - Overview: adr/index.md