docs-4.0.0

.agents/guidelines/documentation.md

@@ -9,28 +9,88 @@
 - `docs/project/` contains authoritative live documentation.
 - `docs/templates/` contains managed reference templates, not requirements.
 - Never edit target templates or copy placeholders and unverified claims into live documents.
+- An untouched scaffold is not a requirement. Treat `Draft`, inferred, and
+  placeholder content as non-authoritative until the project confirms it.
+- An accepted FSD or GDD controls intended behavior. Architecture describes the
+  verified current technical system. An accepted technical design controls only
+  its scoped change.
 
 ## Update the Relevant Document
 
 - setup, commands, configuration, or public usage: `README.md`
 - meaningful changes: `CHANGELOG.md`
-- capability status and links: `docs/project/features.md`
-- stable components, boundaries, integrations, or data flow: `docs/project/architecture.md`
+- accepted application behavior and capabilities: `docs/project/fsd.md`
+- accepted gameplay intent and capabilities: `docs/project/gdd.md`
+- current components, boundaries, runtime, data, deployment, quality approaches,
+  decisions, and technical risks: `docs/project/architecture.md`
 - visible workflows and troubleshooting: `docs/project/user-guide.md`
-- functional, technical, or gameplay requirements: the applicable FSD, TSD, or GDD
+- one substantial proposed technical change:
+  `docs/project/designs/<short-name>.md`, created from
+  `docs/templates/tsd.template.md`
+- optional public capability index: `docs/project/features.md`
 
 Update only documents affected by verified behavior. Do not create documentation as busywork.
 
+## Growth Without Reorganization
+
+Keep `fsd.md`, `gdd.md`, `architecture.md`, and `user-guide.md` as stable
+entry points. When one becomes difficult to navigate, retain a concise overview
+there and link detail under the applicable folder:
+
+- functional detail: `docs/project/functional/`
+- gameplay detail: `docs/project/game-design/`
+- technical detail: `docs/project/architecture/`
+- change designs: `docs/project/designs/`
+- user guidance: `docs/project/guides/`
+
+Do not create empty folders or index files preemptively.
+
+## Technical Designs
+
+Create a design only for a change involving multiple components, public
+contracts, persistence or migration, security, concurrency, deployment,
+compatibility, high uncertainty, or difficult rollback. Routine fixes and
+localized refactors do not need one.
+
+Use `Proposed`, `Accepted`, `Implemented`, `Superseded`, or `Rejected` status.
+After implementation, update architecture with the resulting current state and
+leave the design as historical rationale. Current truth must not remain only in
+an old design.
+
+## Existing-Project Bootstrap
+
+When asked to populate documentation for an existing repository:
+
+1. inspect source, tests, configuration, schemas, workflows, assets, and useful
+   Git history;
+2. populate FSD, GDD, architecture, user guidance, README, and changelog only
+   from relevant evidence;
+3. distinguish intended behavior, verified as-built behavior, local inference,
+   and unknowns where the difference matters;
+4. cite repository evidence for meaningful inferences and request confirmation
+   before treating inferred intent as authoritative;
+5. do not invent historical technical designs or reconstruct changelog entries
+   without evidence.
+
+Game code can establish implemented mechanics but not reliably establish
+intended player experience, balance goals, or future design.
+
 ## Template Review
 
-Scaffolded Markdown contains a source-path marker. It does not track a hash or authorize automatic updates.
+Newly scaffolded Markdown contains source-path and content-hash markers. Sync
+may upgrade it only while those markers prove the live document is unchanged.
+Known older scaffolds may also be upgraded when their recorded provenance or
+an approved legacy content hash verifies the original content.
 
-When a managed template changes, compare it manually with the live document, using Git history when useful. Apply only relevant structural improvements and preserve verified project content. Sync never rewrites live project documentation.
+When a live document cannot be verified, compare it manually with the managed
+template, using Git history when useful. Apply only relevant structural
+improvements and preserve verified project content.
 
 ## Style
 
 - Be concise, factual, and example-driven.
 - Link to detailed documents instead of duplicating them.
+- Keep current state in living documents and proposal history in design records.
 - Curate changelogs; do not paste commit history.
 - Omit unknown information rather than inventing it.
 - Preserve the repository's established formatting and punctuation.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.repo-seed-state.json

@@ -0,0 +1,26 @@
+{
+  "managed_files": {
+    ".agents/conventions/csharp.md": "66f0a42cb7ded64554912ab31de54f6df1026ec912f8369d230606587ff2d04f",
+    ".agents/conventions/python.md": "7707c450df5c2fb809820920304aaa36aef7d5ad1598d5d73ae5dcfaaf3353a6",
+    ".agents/conventions/scripts.md": "b5f2340822cd7402d4eb6087428c0b62ffd71802824559c8492f778afcfda245",
+    ".agents/conventions/shell.md": "165c0382882a8cce818be34368dc5b29a0297d7c2c66a40fd7e4729c397764b9",
+    ".agents/guidelines/ci-cd.md": "e4d6bd8bc0f0696f27501ec87fa3c25d85b103e17bfe7a8993fc61ff63d4faa0",
+    ".agents/guidelines/documentation.md": "07c41e49fabc3ca3807246fe451611b96e6549ac991156e7fbd46271b1bc33f0",
+    ".agents/guidelines/git.md": "4773262f86d33c6e7c8cae87f652a2e4f979de79956bc723a5374dc6889eede5",
+    "AGENTS.md": "6585e8c7d15fbeadb98b3945fd79c575db62ccc3efab39535f2055bc536f0694",
+    "CLAUDE.md": "7050308e6cd5b0b953105fddc8fe5a4d259038dc8de1183414833bc90788554a",
+    "docs/templates/.github/bug-report.template.md": "9e898d893d05a6962300f774120350559082f6b1d68be76e30c2696c1efdb53e",
+    "docs/templates/.github/config.template.yml": "ade4f33049e309848b2f0a64d11c41be3204cd476ac112ee311cdd320cd39313",
+    "docs/templates/.github/feature-request.template.md": "7110742210d16dbf64f01347579189cc653dc049ddcc1386ea4b8325646829ad",
+    "docs/templates/architecture.template.md": "701a4193f0c5eb903af5172e2457af01e5148bddbeae8343b80fa1d02ed4fe90",
+    "docs/templates/changelog.template.md": "731c8ef26b6104fd569f516f344197c0437aa609256aa10257eb3eaff6f6d427",
+    "docs/templates/editorconfig.template": "74b219dcd26beaefc51a9892f5e74b136ac30ff0b04ef70039fbaa9903ead77a",
+    "docs/templates/readme.template.md": "d0be705d90d1c0cff0f27ed9e70f3848a3ad6498f38d918a2821fe4c2e98ba1c",
+    "docs/templates/tsd.template.md": "718bf526bfabaa33b34f6fc80fadca19ff5fae790a07d2a93239b2004607b7bf",
+    "scripts/sync-docs.py": "c6cf2eb16b3b8ebea81308572b0abfc92ab3589ecc98f0c4ff703b8b4068646e"
+  },
+  "pack_version": "4.0.0",
+  "profile": "library",
+  "schema_version": 1,
+  "tombstones": {}
+}

AGENTS.md

@@ -4,7 +4,7 @@ Repository-level instructions for coding agents.
 
 **Document role**: Managed coding-agent instructions
 **Sync destination**: `AGENTS.md`
-**Version**: 3.2.3
+**Version**: 4.0.0
 
 ## Start Here
 
@@ -24,6 +24,8 @@ Instruction precedence is: user request, closest child `AGENTS.md`, `.agents/pro
 - `docs/project/` contains authoritative live project documentation.
 - `docs/templates/` contains managed, read-only references.
 - Never edit target templates or treat their placeholders as requirements.
+- Untouched scaffolds and unconfirmed Draft or inferred content are not
+  authoritative requirements.
 - When behavior changes, update relevant project-owned documentation when practical.
 
 Read `.agents/guidelines/documentation.md` for documentation work or changes affecting setup, behavior, architecture, features, guides, or specifications.
@@ -78,8 +80,10 @@ Read the relevant Git or CI/CD guideline before performing that specialized work
 When provided:
 
 - FSD controls observable behavior and acceptance criteria;
-- TSD controls technical constraints and implementation design;
 - GDD controls gameplay intent and player experience;
+- architecture describes the verified current technical system;
+- an accepted technical design under `docs/project/designs/` controls only its
+  scoped change;
 - tickets and explicit acceptance criteria define task scope.
 
 Report conflicts between requirement sources before implementing.
@@ -98,15 +102,25 @@ Do not run irrelevant language or project checks. Report checks that could not r
 
 ## Sync Ownership
 
-Routine sync overwrites:
+Routine sync updates these files when their pack content differs:
 
 - `AGENTS.md`, `CLAUDE.md`, and selected `.agents/` guidance;
 - `docs/templates/`;
 - `scripts/sync-docs.py`.
 
+Routine sync retires only unchanged legacy-managed files whose hashes match the old manifest. Modified or unrecorded files, reclassified project-owned files, and legacy conflict output are preserved and reported.
+
+Routine sync also maintains committed `.repo-seed-state.json` ownership
+metadata. A smaller profile removes unchanged managed files that are no longer
+selected. Modified stale files are preserved and remain tombstoned for review.
+Do not edit this state file manually.
+
 Do not customize these managed files in target repositories.
 
-Project-owned files include `.agents/project.md`, child `AGENTS.md` files, root `README.md` and `CHANGELOG.md`, `.editorconfig`, `.gitignore`, `docs/project/`, and every unmapped path. Scaffolding creates missing project-owned files but never overwrites them.
+Project-owned files include `.agents/project.md`, child `AGENTS.md` files, root
+`README.md` and `CHANGELOG.md`, `.editorconfig`, `.gitignore`, `docs/project/`,
+and every unmapped path. Scaffolding creates missing project-owned files and
+may upgrade Markdown only while repo-seed provenance proves it unchanged.
 
 ## Completion
 

docs/project/architecture.md

@@ -0,0 +1,69 @@
+# Architecture and Technical Overview
+
+<!-- Scaffolded from: docs/templates/architecture.template.md -->
+<!-- Scaffolded content SHA-256: 4f788d92a2d1f78dd3249ca61a2552af99f3a0d890528bda4f8c6c36232250a7 -->
+
+**Project**:
+**Status**: Draft
+**Last Updated**: YYYY-MM-DD
+
+Describe the verified current technical system. Keep proposed changes in
+`docs/project/designs/` and link them here after they are accepted or implemented.
+
+When this document grows, keep it as the stable overview and move detailed
+subjects under `docs/project/architecture/`. Do not create detail files until
+they add value.
+
+## Purpose, Scope, and Quality Goals
+
+Summarize the system's technical purpose, boundaries, constraints, and the
+three to five quality goals that most influence its design.
+
+## System Context
+
+Define the system boundary, users, and external systems.
+
+## Components and Responsibilities
+
+| Component | Responsibility | Dependencies |
+|---|---|---|
+| | | |
+
+## Important Runtime Flows
+
+Describe the important interactions, including startup, normal operation,
+background processing, failure handling, and shutdown where relevant.
+
+## Data, Interfaces, and Integrations
+
+Describe persistence, APIs, commands, events, contracts, external integrations,
+and important compatibility boundaries.
+
+## Configuration and Deployment
+
+Summarize runtimes, configuration sources, environments, storage, hosting,
+deployment topology, and operational dependencies.
+
+## Cross-Cutting Concerns
+
+Document security, privacy, reliability, observability, performance,
+accessibility, capacity, and compatibility approaches that affect the system.
+
+## Development and Validation
+
+Summarize build boundaries, test levels, local validation, deployment checks,
+and any important environment limitations.
+
+## Decisions and Design Records
+
+Link significant technical designs under `docs/project/designs/`. Record only
+the resulting current state here; do not copy proposal history into this file.
+
+## Risks, Technical Debt, and Open Questions
+
+-
+
+## Detailed Documentation
+
+Link any extracted technical documents. This section may remain empty while the
+overview is sufficient.

docs/templates/.github/bug-report.template.md

@@ -2,7 +2,7 @@
 **Document role**: Managed project-file template
 **Template source**: `docs/templates/.github/bug-report.template.md`
 **Scaffold destination**: `.github/ISSUE_TEMPLATE/bug_report.md`
-**Scaffold behavior**: The live file is project-owned and never overwritten by sync
+**Scaffold behavior**: The live file is project-owned; only a verified unchanged scaffold may be upgraded
 <!-- repo-seed-template:end -->
 
 ---

docs/templates/.github/feature-request.template.md

@@ -2,7 +2,7 @@
 **Document role**: Managed project-file template
 **Template source**: `docs/templates/.github/feature-request.template.md`
 **Scaffold destination**: `.github/ISSUE_TEMPLATE/feature_request.md`
-**Scaffold behavior**: The live file is project-owned and never overwritten by sync
+**Scaffold behavior**: The live file is project-owned; only a verified unchanged scaffold may be upgraded
 <!-- repo-seed-template:end -->
 
 ---

docs/templates/architecture.template.md

@@ -0,0 +1,73 @@
+# Architecture and Technical Overview
+
+<!-- repo-seed-template:start -->
+**Document role**: Managed project-document template
+**Template source**: `docs/templates/architecture.template.md`
+**Scaffold destination**: `docs/project/architecture.md`
+**Scaffold behavior**: The live file is project-owned; only a verified unchanged scaffold may be upgraded
+<!-- repo-seed-template:end -->
+
+**Project**:
+**Status**: Draft
+**Last Updated**: YYYY-MM-DD
+
+Describe the verified current technical system. Keep proposed changes in
+`docs/project/designs/` and link them here after they are accepted or implemented.
+
+When this document grows, keep it as the stable overview and move detailed
+subjects under `docs/project/architecture/`. Do not create detail files until
+they add value.
+
+## Purpose, Scope, and Quality Goals
+
+Summarize the system's technical purpose, boundaries, constraints, and the
+three to five quality goals that most influence its design.
+
+## System Context
+
+Define the system boundary, users, and external systems.
+
+## Components and Responsibilities
+
+| Component | Responsibility | Dependencies |
+|---|---|---|
+| | | |
+
+## Important Runtime Flows
+
+Describe the important interactions, including startup, normal operation,
+background processing, failure handling, and shutdown where relevant.
+
+## Data, Interfaces, and Integrations
+
+Describe persistence, APIs, commands, events, contracts, external integrations,
+and important compatibility boundaries.
+
+## Configuration and Deployment
+
+Summarize runtimes, configuration sources, environments, storage, hosting,
+deployment topology, and operational dependencies.
+
+## Cross-Cutting Concerns
+
+Document security, privacy, reliability, observability, performance,
+accessibility, capacity, and compatibility approaches that affect the system.
+
+## Development and Validation
+
+Summarize build boundaries, test levels, local validation, deployment checks,
+and any important environment limitations.
+
+## Decisions and Design Records
+
+Link significant technical designs under `docs/project/designs/`. Record only
+the resulting current state here; do not copy proposal history into this file.
+
+## Risks, Technical Debt, and Open Questions
+
+-
+
+## Detailed Documentation
+
+Link any extracted technical documents. This section may remain empty while the
+overview is sufficient.