feat(docs): establish MailStack documentation baseline

Author: victorsteele

.github/pull_request_template.md

@@ -8,6 +8,15 @@ Describe the change and the operational problem it solves.
 - [ ] Database and deployment compatibility were reviewed.
 - [ ] Any intentional breaking change is explicitly approved and documented.
 
+## Documentation baseline
+
+- [ ] A `documents/phases/PHASE-NNN-*.md` record was added or updated
+- [ ] User-facing changes update `USER_MANUAL.md`, `HOW_TO_USE.md`, or `ADMIN_GUIDE.md`
+- [ ] `CHANGELOG.md` was updated
+- [ ] `python scripts/manage_documents.py check`
+- [ ] `python scripts/test_documents.py`
+- [ ] `python scripts/check_documentation_policy.py --base HEAD^ --head HEAD`
+
 ## Verification
 
 - [ ] Tests added or updated

.github/workflows/ci.yml

@@ -18,6 +18,8 @@ jobs:
     timeout-minutes: 30
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - uses: actions/setup-python@v5
         with:
@@ -45,6 +47,17 @@ jobs:
       - name: Documentation and metadata validation
         run: python scripts/check_docs.py
 
+      - name: User documentation synchronization
+        run: python scripts/manage_documents.py --root . check
+
+      - name: Documentation system tests
+        run: python scripts/test_documents.py
+
+      - name: Feature documentation policy
+        env:
+          DOCUMENTATION_BASE_SHA: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before }}
+        run: python scripts/check_documentation_policy.py --head "$GITHUB_SHA"
+
       - name: Forensic file inventory
         run: python scripts/generate_inventory.py --root . --check
 

CHANGELOG.md

@@ -16,6 +16,9 @@ All notable repository-level changes are recorded here. Application history befo
 - Removed the stale root `SOURCE_MANIFEST.sha256`; verified release archives continue to generate their own manifest.
 - Made forensic inventory and source-release ordering deterministic across Windows and Linux by sorting canonical POSIX repository-relative paths.
 - Upgraded the pinned Django LTS runtime from 5.2.15 to 5.2.16 to resolve the July 2026 Django security advisories and kept exact-version deployment verification aligned.
+- Established `MAILSTACK-1.3.0-RC1-DOCS-BASELINE-001` as the protected feature and documentation baseline.
+- Added the root `documents/` user-documentation hub with a user manual, task-based how-to guide, administrator guide, baseline record and mandatory phase history.
+- Added deterministic documentation index and manifest synchronization, phase scaffolding, contract tests and CI policy enforcement so maintained feature changes cannot merge without the required user documentation and changelog updates.
 
 ### Compatibility
 
@@ -51,4 +54,4 @@ All notable repository-level changes are recorded here. Application history befo
 
 ### Qualification
 
-Automated gates pass. Stable promotion remains blocked on a clean Ubuntu 24.04 VPS acceptance campaign, external SMTP/LMTP verification, online dependency advisory audit and release-owner legal confirmation.
+Repository CI, the online dependency advisory audit, deterministic release build, release verification and clean-clone verification pass. Stable promotion remains blocked on a clean Ubuntu 24.04 VPS acceptance campaign, external SMTP/LMTP verification, backup/restore acceptance and release-owner legal confirmation.

CONTRIBUTING.md

@@ -23,6 +23,9 @@ pip install -r requirements/development.txt
 From the repository root:
 
 ```bash
+python scripts/manage_documents.py check
+python scripts/test_documents.py
+python scripts/check_documentation_policy.py --base HEAD^ --head HEAD
 python scripts/check_docs.py
 python scripts/validate_templates.py
 python scripts/test_installer.py
@@ -36,10 +39,28 @@ The full gate runs tests, coverage, Ruff, Bandit, Django checks, contact-service
 
 1. Open an issue for significant behavior, schema or deployment changes.
 2. Keep changes narrow and explain compatibility impact.
-3. Add or update tests for every behavior change.
-4. Update documentation, changelog and release notes where applicable.
-5. Do not commit secrets, real mailbox data, personal email addresses, certificates, databases, logs, archives or generated credentials.
-6. Confirm the pull-request checklist and CI results.
+3. Create or update a `documents/phases/PHASE-NNN-*.md` record for every maintained feature phase.
+4. Update `documents/USER_MANUAL.md`, `documents/HOW_TO_USE.md`, or `documents/ADMIN_GUIDE.md` whenever user-visible behavior changes.
+5. Run `python scripts/manage_documents.py sync` and commit the generated documentation index and manifest.
+6. Add or update tests for every behavior change.
+7. Update `CHANGELOG.md`, engineering documentation and release notes where applicable.
+8. Do not commit secrets, real mailbox data, personal email addresses, certificates, databases, logs, archives or generated credentials.
+9. Confirm the pull-request checklist and CI results.
+
+## Documentation-first phase workflow
+
+Start a maintained phase before implementation:
+
+```bash
+python scripts/manage_documents.py new-phase \
+  --phase-id PHASE-001 \
+  --title "Feature title" \
+  --summary "What the phase changes for users"
+```
+
+Complete the generated draft, update the affected guides and changelog, then run `sync`, `check`,
+the documentation contract tests and the feature-change policy. Draft phase documents and stale
+generated documentation cannot pass CI.
 
 ## Coding standards
 

README.md

@@ -188,6 +188,15 @@ ruff check .
 bandit -c .bandit -q -r apps config
 ```
 
+Synchronize and validate user documentation before the complete repository gate:
+
+```bash
+python scripts/manage_documents.py sync
+python scripts/manage_documents.py check
+python scripts/test_documents.py
+python scripts/check_documentation_policy.py --base HEAD^ --head HEAD
+```
+
 Run the complete repository gate from the project root:
 
 ```bash
@@ -232,6 +241,10 @@ See [docs/SCREENSHOTS.md](docs/SCREENSHOTS.md) for the approved screenshot set a
 
 | Area | Document |
 |---|---|
+| User documentation | [documents/README.md](documents/README.md) |
+| User manual | [documents/USER_MANUAL.md](documents/USER_MANUAL.md) |
+| How to use | [documents/HOW_TO_USE.md](documents/HOW_TO_USE.md) |
+| Administrator guide | [documents/ADMIN_GUIDE.md](documents/ADMIN_GUIDE.md) |
 | Quick start | [docs/QUICKSTART.md](docs/QUICKSTART.md) |
 | Installation | [docs/INSTALLATION.md](docs/INSTALLATION.md) |
 | Configuration | [docs/CONFIGURATION.md](docs/CONFIGURATION.md) |

ROADMAP.md

@@ -12,6 +12,12 @@ This roadmap is directional. Security, data integrity and backward compatibility
 - Complete backup, restore and restart-recovery acceptance
 - Confirm source copyright ownership and third-party license compatibility
 
+## Documentation baseline
+
+- Preserve `MAILSTACK-1.3.0-RC1-DOCS-BASELINE-001` as the starting point for future phases
+- Require a phase record, changelog update and affected user-guide update with maintained feature changes
+- Keep the generated user-document index and manifest deterministic and CI-enforced
+
 ## 1.3 stable
 
 - Promote the verified release candidate without feature removal

docs/DEPENDENCY_REVIEW.md

@@ -21,4 +21,4 @@ No obvious conflict was identified between the declared direct dependency licens
 
 ## Vulnerability review
 
-`pip check` passes in the audit environment. Django is pinned to 5.2.16, the upstream July 2026 security release for the 5.2 LTS line. GitHub CI retains `pip-audit` as a blocking network-enabled gate.
+`pip check` passes. Django is pinned to 5.2.16, the July 2026 security maintenance release for the 5.2 LTS line. The blocking network-enabled `pip-audit` gate passed in GitHub Actions run `30133728843` for commit `1e1737edea2e6c922265a15d8584b56671820c65` and remains mandatory for future changes.

docs/FOLDER_STRUCTURE.md

@@ -3,6 +3,8 @@
 ```text
 .github/                    CI, release workflow and contribution templates
 deployment/templates/       Rendered server configuration templates
+documents/                  User manual, how-to, admin guide, phase history and generated manifest
+  phases/                   Mandatory per-phase user and compatibility records
 docs/                       Public architecture, operations and release documentation
 mailbox-app/                Django team mailbox application
   apps/                     Accounts, audit, core, dashboard, ingestion, mailboxes and messages
@@ -14,7 +16,7 @@ mailbox-app/                Django team mailbox application
   templates/                Django HTML templates
   tests/                    Unit, integration, functional, reliability and security tests
 public-site/                Static site and isolated contact WSGI service
-scripts/                    Repository audit, rendering, testing and release tools
+scripts/                    Repository audit, documentation, rendering, testing and release tools
 install.sh                  Clean Ubuntu 24.04 installer
 VERSION                     Canonical release version
 ```

docs/FORENSIC_AUDIT_REPORT.md

@@ -1,16 +1,18 @@
 # Forensic audit report — MailStack 1.3.0 RC1
 
-**Audit date:** 2026-06-30  
-**Release version:** `1.3.0-rc.1`  
-**Target runtime:** Ubuntu Server 24.04 LTS and CPython 3.12  
-**Release classification:** GitHub-ready open-source release candidate
+**Baseline audit date:** 2026-07-24
+**Release version:** `1.3.0-rc.1`
+**Target runtime:** Ubuntu Server 24.04 LTS and CPython 3.12
+**Release classification:** CI-qualified and clean-clone-qualified open-source release candidate
 
 ## Executive disposition
 
 | Gate | Status |
 |---|---|
 | Baseline feature preservation | PASS |
 | Repository structure and public documentation | PASS |
+| User manual, how-to, admin guide and phase-document baseline | PASS |
+| Deterministic documentation index, manifest and change policy | PASS |
 | Complete AGPL-3.0 license text | PASS |
 | Source secret/private-data safety gate | PASS |
 | Python, JSON, YAML and shell syntax | PASS |
@@ -21,13 +23,13 @@
 | Installer and operations contract tests | PASS |
 | Template rendering and placeholder validation | PASS |
 | Forensic file/symbol inventory | PASS |
-| Deterministic release ZIP, manifest and checksum | Required final build gate |
-| Online dependency advisory query | PENDING — audit environment DNS unavailable |
+| Deterministic release ZIP, manifest and checksum | PASS in GitHub CI |
+| Online dependency advisory query | PASS in GitHub CI |
 | Clean Ubuntu 24.04 full-stack acceptance | PENDING external VPS |
 | Real inbound SMTP/LMTP acceptance | PENDING external VPS |
 | Copyright ownership/license confirmation | PENDING release owner |
 
-**OPEN_SOURCE_RELEASE_CANDIDATE:** PASS  
+**OPEN_SOURCE_RELEASE_CANDIDATE:** PASS
 **PRODUCTION_ACCEPTANCE:** PENDING
 
 ## Audited scope
@@ -86,6 +88,8 @@ See `FEATURE_MATRIX.md` for the feature-by-feature verification record.
 10. The complete AGPL-3.0 license text and licensing rationale were added.
 11. A deterministic file/symbol inventory and documentation consistency gate were added.
 12. Local audit virtual environments are ignored without weakening generated-artifact release blocking.
+13. A root `documents/` baseline now provides maintained user, administrator and phase documentation.
+14. Deterministic synchronization, draft blocking and diff-based CI policy prevent maintained feature changes from merging without substantive documentation.
 
 ## Automated evidence
 
@@ -101,16 +105,17 @@ See `FEATURE_MATRIX.md` for the feature-by-feature verification record.
 - Backup/restore/health contracts: **PASS**
 - Shell syntax: **13 files PASS**
 - Source forensic gate: **PASS with zero blocking findings**
-- Documentation gate: **23 required documents PASS**
+- Engineering documentation gate: **PASS**
+- User-document synchronization, manifest and policy tests: **PASS**
 - Python environment consistency (`pip check`): **PASS**
 
-The tests ran locally with Python 3.13.5 because it is the available audit runtime. Package metadata and CI constrain production to Python 3.12 on Ubuntu 24.04.
+The authoritative repository qualification is GitHub Actions run `30133728843` on Ubuntu 24.04 with Python 3.12 at commit `1e1737edea2e6c922265a15d8584b56671820c65`. Local isolated audit environments remain useful for non-networked structural checks but do not replace CI.
 
 ## Security review
 
 Verified controls include root-only generated secrets, strict configuration validation, Argon2 password hashing, CSRF and secure-cookie controls, login throttling, object-level mailbox authorization, safe HTML sanitization, protected attachments, receive-only SMTP, no public registration, no IMAP/POP3/submission in the reference deployment, MariaDB least privilege, systemd sandboxing, safe archive extraction, checksum verification and fail-closed CI/release gates.
 
-The online `pip-audit` command was attempted but could not resolve `pypi.org` in the isolated environment. This is not a passing vulnerability result; the network-enabled CI step remains blocking.
+The network-enabled `pip-audit` command passed as a blocking step in GitHub Actions run `30133728843`. Future dependency changes must continue to pass the locked dependency, `pip check`, and online advisory gates.
 
 ## Performance review
 
@@ -125,7 +130,7 @@ The repository includes an SEO-oriented README, logo asset, release/download/lic
 Before stable promotion:
 
 1. Confirm source ownership and third-party license compatibility.
-2. Require GitHub CI, including the online dependency advisory audit, to pass.
+2. Preserve the successful GitHub CI baseline and require every subsequent release commit to pass all blocking gates.
 3. Install on a clean isolated Ubuntu Server 24.04 VPS.
 4. Verify DNS, MX, PTR/rDNS, TLS, firewall, unknown-recipient rejection, LMTP delivery, ingestion, authorization, contact delivery, backup, restore and restart recovery.
 5. Publish the first version as `v1.3.0-rc.1`; promote to stable only after acceptance.