Publish documentation for Papyrus 0.3.0

.github/workflows/ci.yml

@@ -3,7 +3,7 @@ name: Documentation checks
 on:
   pull_request:
   push:
-    branches: [master]
+    branches: [development, master]
   workflow_dispatch:
 
 permissions:
@@ -17,7 +17,8 @@ jobs:
       - uses: actions/checkout@v4
         with:
           repository: PapyrusReader/server
-          ref: d01f2196c006824dd4be494b1ed43ff3223cd700
+          # Includes the private profile-photo API from server PR #42.
+          ref: 235fd051e2bf72283bcc6da4ecb2d1860b6ef332
           path: .server
       - uses: astral-sh/setup-uv@v6
         with:
@@ -34,3 +35,13 @@ jobs:
           uv run --locked python scripts/export_openapi.py ../_static/openapi.json --check
       - name: Build documentation
         run: make build
+      - name: Validate requirement and task export
+        run: make requirements
+      - name: Test GitHub synchronization and task gates
+        run: make test
+      - uses: actions/upload-artifact@v4
+        with:
+          name: requirements
+          path: |
+            _build/needs/needs.json
+            _build/work-items.json

.github/workflows/deploy.yml

@@ -16,6 +16,7 @@ concurrency:
 
 jobs:
   build:
+    if: github.ref == 'refs/heads/master'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

Makefile

@@ -1,4 +1,4 @@
-.PHONY: install install-dev serve build clean lint
+.PHONY: install install-dev serve build clean lint requirements test project-plan project-sync
 
 install:
 	uv sync --locked
@@ -17,3 +17,16 @@ clean:
 
 lint: build
 	uv run --locked linkchecker _build/html/index.html --check-extern --no-warnings
+
+requirements:
+	uv run --locked sphinx-build -W --keep-going -b needs . _build/needs
+	uv run --locked python scripts/github_work.py export
+
+test:
+	uv run --locked python -m unittest discover -s tests -v
+
+project-plan:
+	uv run --locked python scripts/github_work.py plan
+
+project-sync:
+	uv run --locked python scripts/github_work.py sync

README.md

@@ -1,8 +1,11 @@
 # Papyrus documentation
 
-Sphinx publishes the product requirements, current architecture, and API reference.
-Requirements describe intended capabilities; the implementation chapters describe
-current behavior.
+Sphinx publishes a user manual and technical specification. Requirements describe
+intended capabilities, while implementation notes describe current behavior.
+The [Papyrus GitHub Project](https://github.com/orgs/PapyrusReader/projects/1)
+tracks requirements and tasks across the component repositories.
+
+Published documentation: <https://docs.papyrus-reader.com/>.
 
 ## Setup and preview
 
@@ -15,7 +18,53 @@ make serve
 
 Preview at <http://127.0.0.1:8000>. `make build` produces `_build/html/` and treats
 Sphinx warnings as failures. `make lint` additionally checks external links.
-The Deploy workflow builds with the same lock and publishes GitHub Pages on master.
+Feature/fix PRs target the default `development` branch. CI checks PRs and
+integration pushes without publishing. When ready, promote `development` to
+`master` with a release PR using **Create a merge commit**, then bring `master`
+back into `development`. The Deploy workflow builds with the same lock and
+publishes GitHub Pages only from `master`, including manual runs. Keep both
+long-lived branches and do not squash release promotions.
+
+## Hosting and custom domain
+
+GitHub Pages hosts the documentation independently of the application server.
+In this repository's **Settings → Pages**, use **GitHub Actions** as the build
+source and set the custom domain to `docs.papyrus-reader.com`.
+The DNS record is:
+
+| Type | Name | Target |
+| --- | --- | --- |
+| CNAME | `docs` | `papyrusreader.github.io` |
+
+Use DNS-only routing while GitHub validates the domain and issues its TLS
+certificate, then enable **Enforce HTTPS** in Pages settings. The CNAME target
+must not include `/docs` or a URL scheme. Actions deployments use the custom
+domain from Pages settings, not a repository `CNAME` file. `html_baseurl` in
+`conf.py` sets canonical page URLs to the same HTTPS domain.
+
+After a production deployment, check the homepage, a nested manual page, and
+their styles and navigation at the custom domain. DNS and certificate issuance
+must finish before HTTPS can be verified.
+
+## Requirements and local agents
+
+Run `make requirements` to validate and export the structured requirements and
+tasks, and `make test` to test the synchronization and task eligibility rules.
+CI also performs these checks and uploads the generated JSON as an artifact.
+
+With GitHub CLI authenticated for repository and Projects access:
+
+```bash
+make project-plan
+make project-sync
+uv run --locked python scripts/work_issue.py https://github.com/PapyrusReader/docs/issues/NUMBER --launch
+```
+
+Synchronization requires committed, pushed documentation. It preserves discussion
+outside the managed issue section and does not automatically close requirements.
+Local launches claim only Ready tasks with completed dependencies and prepare an
+isolated checkout. See [the workflow](implementation/github-workflow.rst) for field
+ownership, changed specifications, claim recovery, and PR completion.
 
 ## API snapshot