Documentation Audit Trail

This file tracks all documentation changes for Chatons.

2026-10-08 - Reusable LLM Prefixes

Moved fixed runtime guidance ahead of session-specific context and autocomplete constraints ahead of cursor text. Updated Pi integration, developer guidance and maintainer instructions to document the ordering and preserved harness boundaries. No provider cache flags or conversation-history changes are introduced. Local prompt checks establish stable layout; SSD cache performance requires the target inference server.

2026-05-25 - Isolated Electron Smoke UserData

Documented and tightened the Electron QA user-data override used by smoke tests that send real model prompts.

Changes:

• Updated AGENTS.md to state that CHATON_USER_DATA_DIR is only honored together with CHATON_ALLOW_AUTOMATION_INSTANCE=1
• Updated docs/content/pi-integration.mdx to document isolated QA profiles alongside the managed Pi directory
• Updated docs/content/developer-guide.mdx to describe the startup contract for automation-only user-data overrides

Purpose:

• Lets real Electron prompt smokes run against copied local state without mutating the user's production chaton.sqlite or Pi sessions
• Prevents a stray shell environment variable from silently moving normal app data to another directory
• Keeps QA behavior documented with the main-process runtime contract

2026-04-30 - Runtime Performance Hardening

Documented the extension-server and ACP broadcast performance fixes.

Changes:

• Updated AGENTS.md to require bounded readyUrl probes, coalesced extension server starts, and batched ACP renderer broadcasts
• Updated docs/content/extensions/index.mdx to document bounded readiness probes and per-extension start coalescing for extension authors
• Updated docs/content/pi-integration.mdx and docs/content/developer-guide.mdx to record ACP broadcast batching semantics

Purpose:

• Prevents slow or unreachable extension health endpoints from making startup or extension toggles feel stuck
• Prevents simultaneous extension startup triggers from spawning duplicate local server processes
• Keeps ACP persistence durable while avoiding full SQLite rehydrate and whole-state IPC fanout for every task/status tick

2026-04-23 - Dev Electron Automation Override

Documented the dev-only single-instance override used for real Electron QA automation.

Changes:

• Updated AGENTS.md to record the CHATON_ALLOW_AUTOMATION_INSTANCE=1 dev-only override
• Updated docs/content/developer-guide.mdx and docs/content/pi-integration.mdx to explain when the override is allowed

Purpose:

• Allows automated QA harnesses to launch and drive a second real Electron window during development
• Avoids false negatives where the normal single-instance lock immediately exits the automation target
• Keeps the override clearly scoped to dev/test workflows rather than normal app runtime behavior

2026-04-23 - Extension Server ReadyUrl Reuse

Documented the extension-server startup fix for local channel bridges that keep a port alive across reloads.

Changes:

• Updated AGENTS.md to record that local extension servers may reuse an already-live readyUrl instead of forcing a duplicate bind
• Updated docs/content/extensions/index.mdx to document the readyUrl reuse behavior for extension authors
• Updated docs/content/developer-guide.mdx and docs/content/pi-integration.mdx to explain the Even Realities bridge/runtime behavior

Purpose:

• Prevents false EADDRINUSE startup regressions from being misread as a broken channel bridge
• Keeps runtime readiness aligned with the health endpoint that the UI actually depends on
• Records why a local bridge can remain healthy even when a duplicate child-process launch is skipped

2026-04-22 - Cloud Rollout Shutdown Hardening

Documented the cloud-service shutdown and rollout-diagnostics changes made to reduce stuck Kubernetes deploys.

Changes:

• Updated docs/content/cloud-kubernetes.mdx with the new bounded shutdown behavior for cloud-api, cloud-realtime, and runtime-headless
• Documented that the GitHub Actions deploy workflow now emits pod and deployment diagnostics automatically when rollout waits time out
• Documented that the cloud build now has to copy packages/memory/index.js into dist-cloud so deployed containers can resolve the shared memory module at runtime

Purpose:

• Explains why single-replica rolling updates are now less likely to hang on lingering keep-alive connections or slow store shutdown
• Records the new CI behavior so future rollout failures surface actionable cluster state immediately
• Records the packaging requirement behind the observed ERR_MODULE_NOT_FOUND crash in the live cloud-api rollout

2026-04-22 - ACP Internal Orchestration Documentation

Documented ACP as an internal Chatons orchestration layer over Pi.

Changes:

• Updated AGENTS.md with ACP runtime rules and implementation anchor points
• Updated docs/content/pi-integration.mdx to explain ACP-over-Pi execution
• Updated docs/content/developer-guide.mdx to add ACP to the architecture model

Purpose:

• Clarifies that ACP is an internal typed coordination protocol, not a separate end-user runtime
• Documents the persistence model for ACP envelopes, agent state, and task-list history
• Records the runtime/renderer integration points used for planner/coder/reviewer style flows

2026-04-13 - Cloud Integration Architecture Documentation

Added comprehensive documentation for the Cloud Integration Architecture pattern.

Changes:

• Created new document: docs/content/cloud-integration-architecture.mdx
• Added reference link in documentation index

Purpose:

• Documents the multi-service architecture required for Cloud features
• Describes service dependencies: cloud-api, cloud-realtime, runtime-headless
• Explains internal service token requirements
• Documents URL derivation patterns and their fragility
• Details provider requirements for cloud runtime

Key Sections:

1. Service Stack Overview
2. Critical Dependencies
3. URL Derivation Patterns
4. Provider Requirements
5. Common Failure Modes

---

2026-04-13 - Cloud Onboarding Architecture Documentation

Added documentation for the Cloud Onboarding Architecture pattern.

Changes:

• Added documentation section in AGENTS.md section 12
• Documented the desktop/cloud authentication flow

Key Topics:

• Web-based cloud authentication flow
• Desktop deeplink handling
• Session token management
• OAuth integration details

---

2026-04-13 - Cloud Session Management Documentation

Added documentation for Cloud Session Management pattern.

Changes:

• Added documentation section in AGENTS.md section 13

Key Topics:

• Session token lifecycle (access, refresh, expiry)
• Token refresh limitations
• Session persistence in database
• Session validation flow

---

2026-04-13 - Cloud Project and Conversation Flow Documentation

Added documentation for Cloud Project and Conversation flow.

Changes:

• Added documentation section in AGENTS.md section 14

Key Topics:

• Project creation from desktop
• Repository-based project setup
• Conversation creation for cloud projects
• Runtime provisioning flow
• Error handling and recovery

---

2026-04-13 - Initial Documentation Audit

Changes:

• Migrated documentation from .md files to MDX format in docs/content/
• Removed legacy .md files from docs/
• Created docs/content/documentation-audit.mdx for tracking

---

2026-04-13 - Cloud Integration Architecture Audit

Changes:

• Added comprehensive Cloud Integration Architecture audit findings
• Documented 18 critical findings with severity levels
• Created reference documentation for cloud feature understanding

Key Findings:

1. Desktop connected status can be false positive
2. Session expiration not automatically refreshed
3. Multi-service runtime dependency chain
4. Fragile port conventions for realtime/runtime-headless
5. Runtime fails without exploitable providers
6. Repository projects fail without validation
7. Git not installed in runtime container
8. Errors masked as "unknown"
9. Session quota limits not pre-validated
10. Email verification not enforced
11. Mailer configuration not enforced
12. Organization invite flow incomplete
13. Cloud feature discovery difficult
14. Cloud connect button lacks explanation
15. Arbitrary cloud instance connection limited
16. Project discovery after resync is fragile
17. Cloud conversation titles are ambiguous
18. Realtime disconnection creates confusing state

---