docs: Update AI documentation to accurately reflect current codebase#708
docs: Update AI documentation to accurately reflect current codebase#708
Conversation
- Replace obsolete POLLING_ARCHITECTURE.md with DATA_FETCHING_ARCHITECTURE.md - Rewrite API_NAMING_CONVENTIONS.md with file references instead of code examples - Condense ARCHITECTURE.md from 482 to 195 lines for clarity - Update ETAG_IMPLEMENTATION.md to reflect actual implementation - Update QUERY_PATTERNS.md to reflect completed Phase 5 (nanoid optimistic updates) - Add PRPs/stories/ to .gitignore All documentation now references actual files in codebase rather than embedding potentially stale code examples. Co-Authored-By: Claude <noreply@anthropic.com>
- Update CLAUDE.md to reference documentation files instead of embedding code - Replace Service Layer and Error Handling code examples with file references - Add proper distinction between DATA_FETCHING_ARCHITECTURE and QUERY_PATTERNS docs - Include ETag implementation reference - Update environment variables section with .env.example reference Co-Authored-By: Claude <noreply@anthropic.com>
|
Caution Review failedThe pull request is closed. WalkthroughDocumentation overhaul: consolidates architecture, data-fetching, ETag handling, and naming conventions; introduces TanStack Query patterns and optimistic updates; removes polling doc; updates agent guidance and MCP tool references; adds Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor User
participant UI as Frontend (React + TanStack Query)
participant BrowserCache as Browser Cache (ETag)
participant API as FastAPI Server
rect #eef6ff
note right of UI: Data fetch with browser-managed ETag
User->>UI: View list
UI->>API: GET /api/... (If-None-Match from browser)
alt 304 Not Modified
API-->>UI: 304 Not Modified
UI->>UI: Use cached response (Query cache governed by staleTime)
else 200 OK
API-->>UI: 200 OK + ETag
BrowserCache->>UI: Serve/Store response
UI->>UI: Update application cache
end
end
rect #f0fff4
note right of UI: Optimistic create flow (localId)
User->>UI: Create item
UI->>UI: Insert optimistic entity (_localId)
UI->>API: POST /api/...
alt Success
API-->>UI: 200 OK (real id)
UI->>UI: Replace optimistic entity by _localId
else Error
API-->>UI: 4xx/5xx
UI->>UI: Rollback to previous snapshot
end
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (7)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (14)
AGENTS.md (2)
11-11: Polish phrasing for readability.Use punctuation and hyphenation.
-- **No backwards compatibility we follow a fix forward approach** - remove deprecated code immediately +- **No backwards compatibility; we follow a fix‑forward approach** — remove deprecated code immediately
17-17: Fix apostrophe and grammar.Minor copy tweak.
-- **YAGNI** dont implement features that are not needed +- **YAGNI** — don't implement features that are not neededPRPs/ai_docs/QUERY_PATTERNS.md (2)
181-190: Add language tag to code fences (markdownlint MD040).Label directory trees as text.
-``` +```text src/features/projects/ ├── components/ # UI components ...--- `194-201`: **Add language tag to code fences (markdownlint MD040).** Label directory trees as text. ```diff -``` +```text src/features/projects/tasks/ ├── components/ ...</blockquote></details> <details> <summary>PRPs/ai_docs/API_NAMING_CONVENTIONS.md (2)</summary><blockquote> `128-132`: **Avoid embedding line numbers in file references.** Including “:12” will drift. Remove specific line numbers. ```diff -**Location**: `archon-ui-main/src/features/projects/tasks/types/task.ts:12` +**Location**: `archon-ui-main/src/features/projects/tasks/types/task.ts`
211-214: Clarify file naming guidance.“Always lowercase with ‘Service’ suffix” is ambiguous; prefer “lower camelCase” for file names (projectService.ts).
-- {feature}Service.ts - Service modules -- Always lowercase with "Service" suffix +- {feature}Service.ts - Service modules +- Use lower camelCase with "Service" suffix (e.g., projectService.ts)CLAUDE.md (4)
11-11: Polish phrasing for readability.-- **No backwards compatibility we follow a fix forward approach** - remove deprecated code immediately +- **No backwards compatibility; we follow a fix‑forward approach** — remove deprecated code immediately
17-17: Fix apostrophe and grammar.-- **YAGNI** dont implement features that are not needed +- **YAGNI** — don't implement features that are not needed
187-188: Minor grammar: “type‑safe” and clearer phrasing.-Use database values directly (no mapping in the FE typesafe from BE and up): +Use database values directly (no FE mapping; type‑safe end‑to‑end from BE upward):
262-291: Reduce duplication with AGENTS.md to prevent drift.Consider centralizing shared lists (MCP tools, commands) in one doc and link from the other.
PRPs/ai_docs/ETAG_IMPLEMENTATION.md (1)
83-87: Qualify the “~70%” claim or cite internal measurement.Briefly note this is based on internal measurements to avoid over‑promising.
-- ~70% reduction in data transfer for unchanged responses +- ~70% reduction in data transfer for unchanged responses (based on internal measurements)PRPs/ai_docs/ARCHITECTURE.md (3)
16-31: Add language tag to directory tree fences (markdownlint MD040).-``` +```text server/ # Main FastAPI application ├── api_routes/ # HTTP endpoints ...--- `32-46`: **Add language tag to directory tree fences (markdownlint MD040).** ```diff -``` +```text features/ # Vertical slice architecture ├── knowledge/ # Knowledge base feature ...--- `100-107`: **Add language tag to directory tree fences (markdownlint MD040).** ```diff -``` +```text features/{feature}/ ├── components/ # UI components ...</blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used**: CodeRabbit UI **Review profile**: CHILL **Plan**: Pro <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 0502d378f09521671f5292d99b36fc33311465b6 and bc37b822bec96b4e37042fdc6e3b93738462d1c3. </details> <details> <summary>📒 Files selected for processing (9)</summary> * `.gitignore` (1 hunks) * `AGENTS.md` (8 hunks) * `CLAUDE.md` (8 hunks) * `PRPs/ai_docs/API_NAMING_CONVENTIONS.md` (1 hunks) * `PRPs/ai_docs/ARCHITECTURE.md` (1 hunks) * `PRPs/ai_docs/DATA_FETCHING_ARCHITECTURE.md` (1 hunks) * `PRPs/ai_docs/ETAG_IMPLEMENTATION.md` (1 hunks) * `PRPs/ai_docs/POLLING_ARCHITECTURE.md` (0 hunks) * `PRPs/ai_docs/QUERY_PATTERNS.md` (4 hunks) </details> <details> <summary>💤 Files with no reviewable changes (1)</summary> * PRPs/ai_docs/POLLING_ARCHITECTURE.md </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>🧠 Learnings (23)</summary> <details> <summary>📚 Learning: 2025-08-28T12:06:56.383Z</summary>Learnt from: Wirasm
PR: #514
File: python/src/server/utils/etag_utils.py:27-42
Timestamp: 2025-08-28T12:06:56.383Z
Learning: The ETag implementation in python/src/server/utils/etag_utils.py has known limitations with If-None-Match semantics (wildcards, multiple ETags, weak validators) that are documented in PRPs/ai_docs/ETAG_IMPLEMENTATION.md. These limitations are intentionally not addressed to keep the current implementation simple.**Applied to files:** - `PRPs/ai_docs/ETAG_IMPLEMENTATION.md` </details> <details> <summary>📚 Learning: 2025-09-12T13:47:04.545Z</summary>Learnt from: CR
PR: coleam00/Archon#0
File: AGENTS.md:0-0
Timestamp: 2025-09-12T13:47:04.545Z
Learning: Applies to archon-ui-main/src/**/*.{ts,tsx} : Use HTTP polling with ETag caching; do not introduce WebSocket-based updates in the frontend**Applied to files:** - `PRPs/ai_docs/ETAG_IMPLEMENTATION.md` - `PRPs/ai_docs/DATA_FETCHING_ARCHITECTURE.md` </details> <details> <summary>📚 Learning: 2025-09-13T15:53:40.757Z</summary>Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-13T15:53:40.757Z
Learning: Applies to python/src/server/**/*.py : Implement HTTP polling support and ETag caching on endpoints to enable 304 responses**Applied to files:** - `PRPs/ai_docs/ETAG_IMPLEMENTATION.md` </details> <details> <summary>📚 Learning: 2025-09-12T13:47:04.545Z</summary>Learnt from: CR
PR: coleam00/Archon#0
File: AGENTS.md:0-0
Timestamp: 2025-09-12T13:47:04.545Z
Learning: Applies to archon-ui-main/src/features//services//*.ts : Frontend service method naming: get[Resource]sByProject(projectId), getResource, createResource, update[Resource](id, updates), deleteResource**Applied to files:** - `PRPs/ai_docs/API_NAMING_CONVENTIONS.md` - `AGENTS.md` - `CLAUDE.md` </details> <details> <summary>📚 Learning: 2025-09-12T13:47:04.545Z</summary>Learnt from: CR
PR: coleam00/Archon#0
File: AGENTS.md:0-0
Timestamp: 2025-09-12T13:47:04.545Z
Learning: Applies to archon-ui-main/src/features/**/*.{ts,tsx} : Follow TanStack Query patterns: query-keys factory, smart polling via useSmartPolling, optimistic updates with rollback**Applied to files:** - `PRPs/ai_docs/API_NAMING_CONVENTIONS.md` - `PRPs/ai_docs/DATA_FETCHING_ARCHITECTURE.md` - `AGENTS.md` - `PRPs/ai_docs/QUERY_PATTERNS.md` - `CLAUDE.md` </details> <details> <summary>📚 Learning: 2025-09-13T15:53:40.757Z</summary>Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-13T15:53:40.757Z
Learning: Applies to archon-ui-main/src/**/*.{ts,tsx} : Service method names: get[Resource]sByProject(projectId), getResource, create/update/delete patterns**Applied to files:** - `PRPs/ai_docs/API_NAMING_CONVENTIONS.md` - `AGENTS.md` - `CLAUDE.md` </details> <details> <summary>📚 Learning: 2025-09-13T15:53:40.757Z</summary>Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-13T15:53:40.757Z
Learning: Applies to archon-ui-main/src/**/*.{ts,tsx} : Frontend data fetching must use TanStack Query (no prop drilling) with query key factories, smart polling, and optimistic updates with rollback**Applied to files:** - `PRPs/ai_docs/API_NAMING_CONVENTIONS.md` - `PRPs/ai_docs/DATA_FETCHING_ARCHITECTURE.md` - `AGENTS.md` - `CLAUDE.md` </details> <details> <summary>📚 Learning: 2025-09-13T15:53:40.757Z</summary>Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-13T15:53:40.757Z
Learning: Applies to archon-ui-main/src/features/**/*.{ts,tsx} : Do not use prop drilling for data fetching/state; rely on TanStack Query caches/selectors**Applied to files:** - `PRPs/ai_docs/DATA_FETCHING_ARCHITECTURE.md` </details> <details> <summary>📚 Learning: 2025-09-12T13:47:04.545Z</summary>Learnt from: CR
PR: coleam00/Archon#0
File: AGENTS.md:0-0
Timestamp: 2025-09-12T13:47:04.545Z
Learning: Applies to archon-ui-main/src/**/*.{ts,tsx} : Use TanStack Query for all data fetching; avoid prop drilling**Applied to files:** - `PRPs/ai_docs/DATA_FETCHING_ARCHITECTURE.md` </details> <details> <summary>📚 Learning: 2025-09-12T13:47:04.545Z</summary>Learnt from: CR
PR: coleam00/Archon#0
File: AGENTS.md:0-0
Timestamp: 2025-09-12T13:47:04.545Z
Learning: Prefer detailed, explicit errors over graceful failures during beta to surface issues quickly**Applied to files:** - `AGENTS.md` - `CLAUDE.md` </details> <details> <summary>📚 Learning: 2025-09-13T15:53:40.757Z</summary>Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-13T15:53:40.757Z
Learning: No backwards compatibility during beta; remove deprecated code immediately**Applied to files:** - `AGENTS.md` - `CLAUDE.md` </details> <details> <summary>📚 Learning: 2025-09-12T13:47:04.545Z</summary>Learnt from: CR
PR: coleam00/Archon#0
File: AGENTS.md:0-0
Timestamp: 2025-09-12T13:47:04.545Z
Learning: Applies to python/src/**/*.py : Never accept or store corrupted data (e.g., zero embeddings, null foreign keys, malformed JSON); skip failed items entirely and continue processing**Applied to files:** - `AGENTS.md` - `CLAUDE.md` </details> <details> <summary>📚 Learning: 2025-09-13T15:53:40.757Z</summary>Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-13T15:53:40.757Z
Learning: Applies to python/src/**/*.py : Never accept corrupted data during partial-failure workflows; skip failed items entirely and do not persist partial/placeholder values**Applied to files:** - `AGENTS.md` - `CLAUDE.md` </details> <details> <summary>📚 Learning: 2025-09-13T15:53:40.757Z</summary>Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-13T15:53:40.757Z
Learning: Applies to python/src/**/*.py : Reject invalid data that could corrupt state (e.g., zero embeddings, null FKs, malformed JSON)**Applied to files:** - `AGENTS.md` - `CLAUDE.md` </details> <details> <summary>📚 Learning: 2025-09-12T13:47:04.545Z</summary>Learnt from: CR
PR: coleam00/Archon#0
File: AGENTS.md:0-0
Timestamp: 2025-09-12T13:47:04.545Z
Learning: When updating code, avoid meta-comment keywords like LEGACY/CHANGED/REMOVED; write comments focused solely on current functionality and reasoning**Applied to files:** - `AGENTS.md` - `CLAUDE.md` </details> <details> <summary>📚 Learning: 2025-09-13T15:53:40.757Z</summary>Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-13T15:53:40.757Z
Learning: Remove dead code immediately; avoid backward-compat wrappers/legacy function mappings**Applied to files:** - `AGENTS.md` - `CLAUDE.md` </details> <details> <summary>📚 Learning: 2025-09-13T15:53:40.757Z</summary>Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-13T15:53:40.757Z
Learning: Applies to .env : Optional environment variables may be set: LOGFIRE_TOKEN, LOG_LEVEL, ARCHON_SERVER_PORT, ARCHON_MCP_PORT, ARCHON_UI_PORT**Applied to files:** - `AGENTS.md` - `CLAUDE.md` </details> <details> <summary>📚 Learning: 2025-09-12T13:47:04.545Z</summary>Learnt from: CR
PR: coleam00/Archon#0
File: AGENTS.md:0-0
Timestamp: 2025-09-12T13:47:04.545Z
Learning: Applies to .env : Ensure required environment variables are present: SUPABASE_URL and SUPABASE_SERVICE_KEY; optional LOGFIRE_TOKEN, LOG_LEVEL, ARCHON_*_PORTs**Applied to files:** - `AGENTS.md` - `CLAUDE.md` </details> <details> <summary>📚 Learning: 2025-09-13T15:53:40.757Z</summary>Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-13T15:53:40.757Z
Learning: Applies to .env : Define required environment variables: SUPABASE_URL and SUPABASE_SERVICE_KEY**Applied to files:** - `AGENTS.md` - `CLAUDE.md` </details> <details> <summary>📚 Learning: 2025-09-13T15:53:40.757Z</summary>Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-13T15:53:40.757Z
Learning: Applies to python/src/mcp_server/features/**/*.py : Place MCP tools under python/src/mcp_server/features/[feature]/ named find_[resource] and manage_[resource] patterns**Applied to files:** - `AGENTS.md` - `CLAUDE.md` </details> <details> <summary>📚 Learning: 2025-09-13T15:53:40.757Z</summary>Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-13T15:53:40.757Z
Learning: Applies to python/src/mcp_server/features/**/init.py : Register MCP tools in the feature package’s init.py**Applied to files:** - `AGENTS.md` - `CLAUDE.md` </details> <details> <summary>📚 Learning: 2025-09-12T13:47:04.545Z</summary>Learnt from: CR
PR: coleam00/Archon#0
File: AGENTS.md:0-0
Timestamp: 2025-09-12T13:47:04.545Z
Learning: Remove deprecated or dead code immediately; no backward compatibility is maintained**Applied to files:** - `CLAUDE.md` </details> <details> <summary>📚 Learning: 2025-09-13T15:53:40.757Z</summary>Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-13T15:53:40.757Z
Learning: Applies to archon-ui-main/src/**/*.{ts,tsx} : State naming: use is[Action]ing for loading, [resource]Error for errors, selected[Resource] for selections**Applied to files:** - `CLAUDE.md` </details> </details><details> <summary>🪛 markdownlint-cli2 (0.17.2)</summary> <details> <summary>AGENTS.md</summary> 16-16: Fenced code blocks should have a language specified (MD040, fenced-code-language) </details> </details> </details> <details> <summary>🔇 Additional comments (10)</summary><blockquote> <details> <summary>.gitignore (1)</summary><blockquote> `7-7`: **LGTM: targeted ignore entry is appropriate.** Ignoring PRPs/stories/ is consistent with existing PRPs/* patterns. No further action. </blockquote></details> <details> <summary>AGENTS.md (3)</summary><blockquote> `296-303`: **Align wording with Data Fetching docs (Query + smart polling).** Current line suggests “HTTP polling handles all updates,” which can be read as polling-first. Suggest emphasizing TanStack Query with optional smart polling. [suggest_minor_issue] ```diff -- HTTP polling handles all updates +- TanStack Query handles all data fetching; smart HTTP polling is used where appropriate (no WebSockets)
139-148: Verify the @PRPs/... reference syntax resolves on your docs site.
If the renderer doesn’t auto-link this notation, replace with relative links.
Location: AGENTS.md lines 139–148 — references: @PRPs/ai_docs/ARCHITECTURE.md, @PRPs/ai_docs/DATA_FETCHING_ARCHITECTURE.md, @PRPs/ai_docs/QUERY_PATTERNS.md.
266-293: MCP tool names and registrations verifiedfind_/manage_ functions exist in project_tools.py, task_tools.py, document_tools.py and version_tools.py, and each feature package init.py exports the corresponding register_tools; rag exposes register_rag_tools for its rag tools — no drift detected.
PRPs/ai_docs/QUERY_PATTERNS.md (1)
225-232: Clarify “Removed ETag cache layer” to avoid confusion.Make it explicit this refers to the former manual frontend layer; backend ETags remain.
[suggest_minor_issue]-- ✅ Phase 1: Removed ETag cache layer +- ✅ Phase 1: Removed manual frontend ETag cache layer (backend ETags remain; browser-managed)CLAUDE.md (2)
294-301: Align wording with Data Fetching docs.Prefer emphasizing Query with optional smart polling.
[suggest_minor_issue]-- HTTP polling handles all updates +- TanStack Query handles all data fetching; smart HTTP polling is used where appropriate (no WebSockets)
139-148: Confirm '@PRPs/…' link resolution or convert to relative links.PRPs/ai_docs/* files exist, but I found no repo config mapping the '@prps' shorthand (checked tsconfig paths and docs/docusaurus config). Replace with relative links or add a renderer alias. Locations: CLAUDE.md:139–148; AGENTS.md:139–147; PRPs/templates/prp_base.md:57.
PRPs/ai_docs/DATA_FETCHING_ARCHITECTURE.md (1)
5-6: Clarify “replaces polling-based architecture”.Avoid implying polling is gone; it’s now integrated via TanStack Query’s patterns.
[suggest_minor_issue]-Archon uses **TanStack Query v5** for all data fetching, caching, and synchronization. This replaces the previous polling-based architecture with a more sophisticated query-based system that handles caching, deduplication, and smart refetching automatically. +Archon uses **TanStack Query v5** for all data fetching, caching, and synchronization. This replaces the former custom polling layer with a query‑centric design that handles caching, deduplication, and smart refetching (including visibility‑aware polling) automatically.PRPs/ai_docs/API_NAMING_CONVENTIONS.md (1)
87-91: Verified — referenced service file paths exist.
All four referenced service files are present at the documented paths.PRPs/ai_docs/ETAG_IMPLEMENTATION.md (1)
21-26: Double‑check fetch + 304 behavior; add Cache‑Control guidance.
- Server already sets ETag and Cache‑Control:
no-cache, must-revalidate(see python/src/server/api_routes/progress_api.py and python/src/server/api_routes/projects_api.py where 304 responses and headers are emitted).- Browsers: per the Fetch spec, a 304 freshens the HTTP cache and the browser/fetch() will typically return the cached stored response (so JS usually sees the cached body, not an empty 304).
- Non‑browser runtimes (React Native, some custom fetch implementations) can surface a 304 with no body to JS — add/document a client fallback in apiWithEtag.ts to return TanStack Query’s cached data or otherwise handle status 304/empty body.
- Update ETAG_IMPLEMENTATION.md to: state the server sends
Cache-Control: no-cache, must-revalidate, explain browser vs non‑browser fetch behavior, and reference the client fallback (apiWithEtag.ts).
- Fix punctuation, hyphenation, and grammar issues across all docs - Add language tags to directory tree code blocks for proper markdown linting - Clarify TanStack Query integration (not replacing polling, but integrating it) - Add Cache-Control header documentation and browser vs non-browser fetch behavior - Reference actual implementation files for polling intervals instead of hardcoding values - Improve type-safety phrasing and remove line numbers from file references - Clarify Phase 1 removed manual frontend ETag cache (backend ETags remain) Co-Authored-By: Claude <noreply@anthropic.com>
…oleam00#708) * docs: Update AI documentation for accurate codebase reflection - Replace obsolete POLLING_ARCHITECTURE.md with DATA_FETCHING_ARCHITECTURE.md - Rewrite API_NAMING_CONVENTIONS.md with file references instead of code examples - Condense ARCHITECTURE.md from 482 to 195 lines for clarity - Update ETAG_IMPLEMENTATION.md to reflect actual implementation - Update QUERY_PATTERNS.md to reflect completed Phase 5 (nanoid optimistic updates) - Add PRPs/stories/ to .gitignore All documentation now references actual files in codebase rather than embedding potentially stale code examples. * docs: Update CLAUDE.md and AGENTS.md with current patterns - Update CLAUDE.md to reference documentation files instead of embedding code - Replace Service Layer and Error Handling code examples with file references - Add proper distinction between DATA_FETCHING_ARCHITECTURE and QUERY_PATTERNS docs - Include ETag implementation reference - Update environment variables section with .env.example reference * docs: apply PR review improvements to AI documentation - Fix punctuation, hyphenation, and grammar issues across all docs - Add language tags to directory tree code blocks for proper markdown linting - Clarify TanStack Query integration (not replacing polling, but integrating it) - Add Cache-Control header documentation and browser vs non-browser fetch behavior - Reference actual implementation files for polling intervals instead of hardcoding values - Improve type-safety phrasing and remove line numbers from file references - Clarify Phase 1 removed manual frontend ETag cache (backend ETags remain)
…phan conversations (#726) * fix(web): add cancel confirmation, surface rename errors, clean up orphan conversations (#708) Workflow cancel button now shows a confirmation dialog before cancelling. Conversation rename errors are displayed inline instead of silently logged. Orphan conversations created before a workflow run failure are cleaned up. Changes: - WorkflowProgressCard: wrap Cancel button with AlertDialog confirmation - ConversationItem: add renameError state and inline error display - WorkflowInvoker: track conversationId and delete on runWorkflow failure - WorkflowList: same orphan cleanup pattern as WorkflowInvoker Fixes #708 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * chore: Auto-commit workflow artifacts (archon-fix-github-issue) * fix(web): fix delete/rename ID mismatch, harden error handling (#708) - Fix broken delete/rename: was sending database UUID instead of platform_conversation_id to API endpoints that expect platform IDs - Hoist AlertDialog outside workflow status conditional to prevent unmounting mid-interaction when SSE status updates arrive - Add console.warn for orphan conversation cleanup failures instead of silently swallowing errors (CLAUDE.md compliance) - Scope orphan cleanup to only fire before runWorkflow starts to prevent deleting active conversations on client network errors - Use err: unknown with instanceof guards on all catch blocks - Surface useQuery errors with error UI instead of misleading empty state - Re-open delete dialog on error so users see failure messages Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
…phan conversations (coleam00#726) * fix(web): add cancel confirmation, surface rename errors, clean up orphan conversations (coleam00#708) Workflow cancel button now shows a confirmation dialog before cancelling. Conversation rename errors are displayed inline instead of silently logged. Orphan conversations created before a workflow run failure are cleaned up. Changes: - WorkflowProgressCard: wrap Cancel button with AlertDialog confirmation - ConversationItem: add renameError state and inline error display - WorkflowInvoker: track conversationId and delete on runWorkflow failure - WorkflowList: same orphan cleanup pattern as WorkflowInvoker Fixes coleam00#708 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * chore: Auto-commit workflow artifacts (archon-fix-github-issue) * fix(web): fix delete/rename ID mismatch, harden error handling (coleam00#708) - Fix broken delete/rename: was sending database UUID instead of platform_conversation_id to API endpoints that expect platform IDs - Hoist AlertDialog outside workflow status conditional to prevent unmounting mid-interaction when SSE status updates arrive - Add console.warn for orphan conversation cleanup failures instead of silently swallowing errors (CLAUDE.md compliance) - Scope orphan cleanup to only fire before runWorkflow starts to prevent deleting active conversations on client network errors - Use err: unknown with instanceof guards on all catch blocks - Surface useQuery errors with error UI instead of misleading empty state - Re-open delete dialog on error so users see failure messages Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
…phan conversations (coleam00#726) * fix(web): add cancel confirmation, surface rename errors, clean up orphan conversations (coleam00#708) Workflow cancel button now shows a confirmation dialog before cancelling. Conversation rename errors are displayed inline instead of silently logged. Orphan conversations created before a workflow run failure are cleaned up. Changes: - WorkflowProgressCard: wrap Cancel button with AlertDialog confirmation - ConversationItem: add renameError state and inline error display - WorkflowInvoker: track conversationId and delete on runWorkflow failure - WorkflowList: same orphan cleanup pattern as WorkflowInvoker Fixes coleam00#708 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * chore: Auto-commit workflow artifacts (archon-fix-github-issue) * fix(web): fix delete/rename ID mismatch, harden error handling (coleam00#708) - Fix broken delete/rename: was sending database UUID instead of platform_conversation_id to API endpoints that expect platform IDs - Hoist AlertDialog outside workflow status conditional to prevent unmounting mid-interaction when SSE status updates arrive - Add console.warn for orphan conversation cleanup failures instead of silently swallowing errors (CLAUDE.md compliance) - Scope orphan cleanup to only fire before runWorkflow starts to prevent deleting active conversations on client network errors - Use err: unknown with instanceof guards on all catch blocks - Surface useQuery errors with error UI instead of misleading empty state - Re-open delete dialog on error so users see failure messages Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
1 participant
Pull Request
Summary
Updates all AI documentation files to accurately reflect the current codebase after Phase 5 completion. Prevents documentation drift by using file references instead of embedded code examples.
Changes Made
Type of Change
Affected Services
Testing
Test Evidence
Checklist
Breaking Changes
None - documentation only changes
Additional Notes
Summary by CodeRabbit
Documentation
Chores