docs update (wip)

src/models.py

@@ -1,3 +1,41 @@
+"""
+Models - Core data structures for MMA orchestration and project configuration.
+
+This module defines the primary dataclasses used throughout the Manual Slop
+application for representing tasks, tracks, and execution context.
+
+Key Data Structures:
+ - Ticket: Atomic unit of work with status, dependencies, and context requirements
+ - Track: Collection of tickets with a shared goal
+ - WorkerContext: Execution context for a Tier 3 worker
+ - Metadata: Track metadata (id, name, status, timestamps)
+ - TrackState: Serializable track state with discussion history
+ - FileItem: File configuration with auto-aggregate and force-full flags
+
+Status Machine (Ticket):
+ todo -> in_progress -> completed
+   |          |
+   v          v
+ blocked   blocked
+
+Serialization:
+ All dataclasses provide to_dict() and from_dict() class methods for TOML/JSON
+ persistence via project_manager.py.
+
+Thread Safety:
+ These dataclasses are NOT thread-safe. Callers must synchronize mutations
+ if sharing instances across threads (e.g., during ConductorEngine execution).
+
+Configuration Integration:
+ - load_config() / save_config() read/write the global config.toml
+ - AGENT_TOOL_NAMES defines the canonical list of MCP tools available to agents
+
+See Also:
+ - docs/guide_mma.md for MMA orchestration documentation
+ - src/dag_engine.py for TrackDAG and ExecutionEngine
+ - src/multi_agent_conductor.py for ConductorEngine
+ - src/project_manager.py for persistence layer
+"""
 from __future__ import annotations
 import tomllib
 import datetime