WorldSharp Documentation

This folder records durable decisions, the reasoning behind them, proposals and alternatives, implementation status, and deliberately deferred work. Documentation is part of the implementation: when code changes a lasting architectural or product decision, update the relevant current-state section without deleting the longer-term rationale.

Current documents deliberately separate:

1. enduring vision and principles — what future work should preserve and why;
2. proposed/future architecture and alternatives — desired but not necessarily implemented;
3. current implementation, status, and gaps — claims that must agree with code and tests.

Documents

• Architecture — dependency and ownership boundaries, deployment, persistence, and future composition.
• Extension System — static registration, current contracts, and extension limits.
• Driver Architecture — accepted replaceable execution strategy, profiles/runs proposal, roadmap, and current Driver seams.
• Perspective Roleplay Driver — the isolated source-to-POV projection, Character response, and no-perception turn design.
• Text-First Roleplay Messages — accepted Driver-owned editable message documents and the planned removal of projection-specific service persistence.
• World Model — Universe ownership, emergent geography, graph/history ideals, and implemented durable records.
• World Tracking, Time, and Scenes — review-first history, chronology models, Scene design, and implemented tracker lifecycle.
• Interfaces and Modes — mode ownership, cardinality and shell ideals, and current Interface/Scene behavior.
• Tavern Compatibility and Imports — compatibility boundary, ephemeral chat and Content Pack proposals, and implemented imports.
• User Interface — visual and interaction principles plus current surfaces.
• UI Architecture — persistent workspace and drawer/tool proposal alongside the current shell.
• Provider Connections — external provider configuration.
• Development Rules — codebase conventions.

Historical sources

docs/archive/ preserves the original LLMToy and Marinara transcripts and proposals, including the Marinara Driver proposal. They explain where decisions came from but are not current API specifications.

Documentation rules

1. Preserve architectural intent and history even when implementation advances.
2. Label proposals as proposals and current behavior as current behavior.
3. Retain useful factual corrections; do not restore an obsolete claim merely because it appeared in an earlier draft.
4. Record alternatives, rationale, and intentional deferrals so future work can revisit decisions without reconstructing them from commits.
5. Update documentation and code together whenever one constrains the other.