Sweep of the per-source-file guides + Readme.md for stale references
to src/models.py as the data model home. models.py is now a ~1.5KB
re-export shim per module_taxonomy_refactor_20260627; dataclasses
moved to src/mma.py, src/project_files.py, src/type_aliases.py,
src/mcp_tool_specs.py, src/result_types.py, src/context_presets.py,
src/workspace_manager.py, src/personas.py.
- guide_gui_2.md: _gui_func line 754->1062; render_main_interface
line 1259->1898.
- python.md §10 exemption table: App gui_2.py:307->314; AppController
795->801; RAGEngine 123->125; HookServer 856->941;
HookServerInstance 130->171; HookHandler 155->208;
WebSocketServer 908->993.
- guide_multi_agent_conductor.md: Ticket now in src/mma.py (not
models.py); ConductorEngine 116+->112+; WorkerPool 50-114->52-110.
- guide_agent_memory_dimensions.md: FileItem ref models.py:510-559
-> src/project_files.py.
- guide_context_aggregation.md: FileItem + ContextPreset refs ->
src/project_files.py + src/context_presets.py; ai_client _send_*
count 5->8.
- guide_discussions.md: parse_history_entries now in src/mma.py;
ContextPreset/FileItem cross-refs updated.
- guide_personas.md: Persona now in src/personas.py; import example
updated.
- guide_rag.md: RAGConfig now in src/mcp_client.py.
- guide_workspace_profiles.md: WorkspaceProfile now in
src/workspace_manager.py.
- guide_mma.md: Data Structures section notes src/mma.py as the live
location.
- Readme.md: MMA Engine + Data Models rows updated for the
models.py shim reality + 8 providers + mma_exec deprecation.
- guide_ai_client.md: '5 provider SDKs'->8 (added note); PROVIDERS
line 56->62; __getattr__ re-export line 261->31; provider
switching examples use real registered model names (claude-sonnet-
4-5, MiniMax-M2, gemini-2.5-flash, qwen-plus, grok-2, llama-3.1);
_provider union lists all 8 providers.
Documents the two bugs fixed in the rag_test_failures_20260615 track:
1. get_all_indexed_paths: m.get('path') failing on None metadata
2. _validate_collection_dim_result: 'if not embeddings' raising
ValueError on non-empty numpy arrays
Also documents the 'no such table: tenants' chromadb corruption
symptom (wipe .slop_cache/chroma_* to recover).
Plus: 'rag_status' shows 'error: ' prefix is the failure indicator;
the actual error message is the part after the prefix.
Re-audit after reading the actual full file contents:
1. guide_app_controller.md (the __init__ walkthrough):
- '4-thread ThreadPoolExecutor' -> '8-thread' per IO_POOL_MAX_WORKERS = 8
in src/io_pool.py:20 (bumped from 4 in commit 4a338486; the io_pool.py
module docstring is also stale and says '4 worker threads' - flagged
for a separate fix).
- '12 locks' -> '11 locks + 5 non-lock state fields' (re-counted the
threading.Lock() and the _rag_sync_*/_project_switch_* fields).
2. guide_app_controller.md (the closing line):
- '12 locks' -> removed; explained the 434-line __init__ body
composition (locks + state fields + settable_fields + gui_task_handlers).
3. guide_rag.md (Future Work section):
- 'The _search_mcp method is a placeholder for this' -> WRONG.
_search_mcp (src/rag_engine.py:322) IS a real implementation that
calls mcp_client.async_dispatch when vector_store.provider == 'mcp'.
Rewrote the future-work item to describe the actual mechanism.
4. docs/reports/docs_sync_test_era_20260610.md (the closing report):
- Same 4-thread->8 and 12-locks->11 corrections propagated.
The structural facts (WorkspaceProfile/RAGConfig/VectorStoreConfig field
lists, method existence, _init_actions/_load_active_project line
numbers, _LiveGuiHandle existence, etc.) were all correct. The
counting/threading-pool claims I cited from memory were the ones
that needed re-verification.
The previous note in guide_rag.md §RAGConfig Schema said:
'ast_chunking_enabled lives in ChunkingConfig (not in RAGConfig)'
This was a documentation lie. Verified by grep:
- 'class ChunkingConfig' returns 0 matches in src/
- 'ast_chunking_enabled' returns 0 matches anywhere in src/
- The 5 fields (ast_chunking_enabled, auto_index_on_load,
auto_sync_interval_seconds, vector_store_backend, vector_store_path)
were never in the real RAGConfig. They were fictional.
Rewrite the note to be honest: 'the old doc was fictional; the
real RAGConfig has 5 fields; the other 5 fields never existed'.
Clarify that top_k is a real runtime parameter (on
RAGEngine.search()) not a config field.
Gitea (and any case-sensitive filesystem) was rendering the [Top]
nav links in /docs as broken because of two bugs:
1. Case-sensitivity: 22 links used '../README.md' (all-uppercase)
but the actual file is 'docs/Readme.md' (capital R, lowercase
rest). 21 guide_*.md nav bars were affected, plus 1 internal
cross-link in Readme.md itself. Works on Windows (case-
insensitive) but broken on Linux/Gitea.
Fix: 22 occurrences across 22 files changed
'../README.md' -> '../Readme.md'
2. Wrong relative-path level: 16 links used '../../conductor/...'
from 'docs/guide_*.md' to reach 'conductor/'. This goes up 2
levels to 'projects/', which doesn't exist. The correct path
from 'docs/guide_*.md' to 'conductor/' is 1 level up
('../conductor/...'). 12 unique patterns across 10 files
affected.
Fix: 16 occurrences across 10 files changed
'../../conductor/' -> '../conductor/'
3. Bonus: 1 planned-guide link in guide_context_curation.md
referenced a never-written 'guide_context_presets.md'. The
ContextPreset schema is now fully covered in the new
'guide_context_aggregation.md' (per the 2026-06-08 docs
refresh). Fix: link target updated.
No content was changed, only link paths. 24 files, 37 link
replacements, 37 deletions.
Verification:
- All .md links in docs/ now resolve to existing files
(validated by path-resolution check from each file's directory)
- The 3 new guides from the previous docs refresh commit
(guide_discussions.md, guide_state_lifecycle.md,
guide_context_aggregation.md) had the case bug inherited from
guide_architecture.md's existing nav pattern; their top-of-file
nav bars are now correct
- The 21 pre-existing guide nav bars that had the same bug
(all 21 of them, except the 3 that used the correct case:
guide_mma.md, guide_simulations.md, guide_tools.md) are now
also fixed
- Inter-guide links (e.g. [Discussions](guide_discussions.md))
were not affected; they were always correct because both the
link text and the actual filename are lowercase
This is a docs-only fix. No code modified.
ed
conductor-tier2