README.md

AI Documentation

The documents describe the agreed-upon architecture and are the source of truth for implementation. When a key decision changes, the corresponding ADR is created or updated first, then the affected documents are updated in lockstep.

Reading order

1. Product requirements and boundaries
2. Architecture
3. Domain model
4. JSON storage
5. MCP integration
6. Security
7. AI endpoints and agent loop
8. Implementation plan
9. Testing strategy
10. Operations and diagnostics
11. Implementation progress
12. UX decisions
13. Headless chat testing
14. Concurrent chat runs
15. Logging
16. Composer rules
17. Default MCP tools
18. Application management tools
19. Compact turn view
20. Asking the user (ask_user)
21. LLM context management
22. Tool selection and adaptive compaction
23. Hidden model instructions and run completion
24. Desktop app
25. Chat artifacts and reviews (proposal)
26. Long-term memory and project instructions
27. Skills
28. Token usage
29. Chat widgets
30. Dependency injection with Pure.DI
31. Context request budgets and quality evaluation
32. Styles and palette
33. Asides and team messages

Generator diagnostics and complaints are tracked separately in Pure.DI observations and issues.

Accepted decisions

• ADR-001: Hosted Blazor WebAssembly
• ADR-002: JSON graph of immutable nodes
• ADR-003: Per-tool MCP permissions
• ADR-004: Responses API as the primary OpenAI protocol
• ADR-005: Fast unit tests on xUnit
• ADR-006: Architecture simplification
• ADR-007: Application management tools in an in-process MCP server
• ADR-008: Desktop app on Avalonia with the system web view
• ADR-009: One adaptive context policy
• ADR-010: Adaptive compaction decisions and measured savings
• ADR-011: Budgeted summary requests and separate quality evaluations
• ADR-012: Comparable prefix overlap and adaptive tool headroom

Document status

All listed documents have the status Accepted and capture decisions made before implementation began. NuGet package versions must be set centrally in Directory.Packages.props; the latest compatible stable version is chosen during implementation and pinned by the lock file.

The actual state of work, verification results, and the next increment are recorded in Implementation progress. It has the status Active and is updated after each completed increment.

Language convention

All UI text, source-code comments, identifiers, technical messages, and project documentation introduced by the project are written in English.

Current decisions: ADR-006.

• Default MCP tools — process execution, permissions, and CLI.