Integrate repository cleanup and enforce reader reference consistency

.github/workflows/tooling.yml

@@ -6,11 +6,17 @@ on:
       - 'tools/**'
       - '.vscode/setup.sh'
       - '.github/workflows/tooling.yml'
+      - 'client'
+      - 'reader'
+      - '.gitmodules'
   pull_request:
     paths:
       - 'tools/**'
       - '.vscode/setup.sh'
       - '.github/workflows/tooling.yml'
+      - 'client'
+      - 'reader'
+      - '.gitmodules'
   workflow_dispatch:
 
 permissions:
@@ -21,6 +27,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: recursive
       - uses: actions/setup-python@v5
         with:
           python-version: '3.12'
@@ -32,3 +40,5 @@ jobs:
         run: tools/papyrus check tooling
       - name: Check setup script
         run: shellcheck .vscode/setup.sh
+      - name: Check committed reader references
+        run: tools/papyrus check references

.vscode/tasks.json

@@ -185,6 +185,57 @@
         "panel": "dedicated",
         "reveal": "always"
       }
+    },
+    {
+      "label": "Check reader",
+      "type": "process",
+      "command": "${workspaceFolder}/tools/papyrus",
+      "args": [
+        "check",
+        "reader"
+      ],
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "problemMatcher": [],
+      "presentation": {
+        "panel": "dedicated",
+        "reveal": "always"
+      }
+    },
+    {
+      "label": "Test reader",
+      "type": "process",
+      "command": "${workspaceFolder}/tools/papyrus",
+      "args": [
+        "test",
+        "reader"
+      ],
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "problemMatcher": [],
+      "presentation": {
+        "panel": "dedicated",
+        "reveal": "always"
+      }
+    },
+    {
+      "label": "Check all",
+      "type": "process",
+      "command": "${workspaceFolder}/tools/papyrus",
+      "args": [
+        "check",
+        "all"
+      ],
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "problemMatcher": [],
+      "presentation": {
+        "panel": "dedicated",
+        "reveal": "always"
+      }
     }
   ],
   "inputs": [

AGENTS.md

@@ -27,8 +27,8 @@ Flutter is pinned in `.fvmrc` to the client CI version; use `tools/flutter` and
 `tools/dart` rather than the machine's potentially newer SDK.
 
 - `tools/papyrus doctor`: tools, SDK, local configuration, submodules, GitHub auth.
-- `tools/papyrus deps client|server`: locked dependency setup.
-- `tools/papyrus check client|server|tooling`: non-mutating quality checks.
+- `tools/papyrus deps client|reader|server|all`: locked dependency setup.
+- `tools/papyrus check client|reader|server|references|tooling|all`: non-mutating quality checks.
 - `tools/papyrus test client -- test/path_test.dart`: focused Flutter test.
 - `tools/papyrus test server -- tests/services/test_sync.py`: focused pytest run.
 - `tools/papyrus run client|server`: development processes.
@@ -60,4 +60,4 @@ contract decisions with both implementers and run database tests serially.
 Follow the existing design tokens and e-ink motion preferences. Library operations
 must work offline and remain isolated across guest, user, and server profiles.
 Treat stored reading positions and user media as durable data. See
-`DEVELOPMENT.md` for setup, measured baseline and known gaps.
+`DEVELOPMENT.md` for setup, checks and integration workflow.

DEVELOPMENT.md

@@ -3,8 +3,8 @@
 Papyrus is a workspace of independent Git submodules. The client is Flutter with
 Provider, SQLite/PowerSync, platform adapters and a Git-pinned EPUB/PDF reader.
 The server is FastAPI with async SQLAlchemy, Pydantic, Alembic, PostgreSQL and a
-self-hosted PowerSync service. Inspect the source for implemented capabilities;
-some README feature lists and setup links are ahead of the current checkout.
+self-hosted PowerSync service. Product requirements describe planned capabilities; component READMEs and source
+describe current behavior.
 
 ## Setup
 
@@ -49,11 +49,14 @@ directory. All subprocesses use the appropriate component directory.
 | `tools/papyrus doctor` | Inspect tools, config, SDK, repos, Docker and GitHub authentication |
 | `tools/papyrus sdk` | Install/link the FVM version from `.fvmrc` |
 | `tools/papyrus deps client` | Install client dependencies with its committed lock |
+| `tools/papyrus deps reader` | Install reader dependencies with its committed lock |
 | `tools/papyrus deps server` | Install server/dev dependencies with the uv lock |
 | `tools/papyrus check client` | Non-writing Dart format check, Flutter analysis, four web-bootstrap tests |
 | `tools/papyrus check server` | Ruff lint, Ruff format check, strict Mypy |
-| `tools/papyrus check tooling` | Eight CLI regression tests and ShellCheck |
-| `tools/papyrus check all` | All three check groups above; reports independent failures |
+| `tools/papyrus check reader` | Formatting, worker asset drift, library and example analysis |
+| `tools/papyrus check references` | Match committed workspace reader and client dependency revisions |
+| `tools/papyrus check tooling` | CLI regression tests and ShellCheck |
+| `tools/papyrus check all` | Tooling, reference consistency, client, reader and server; reports independent failures |
 | `tools/papyrus test client -- test/auth/token_store_test.dart` | Focused Flutter tests; pass options after `--` |
 | `tools/papyrus test client -- --coverage` | Full client suite and coverage |
 | `tools/papyrus test server -- tests/services/test_sync.py` | Focused backend tests |
@@ -63,9 +66,18 @@ directory. All subprocesses use the appropriate component directory.
 
 Use `tools/flutter` and `tools/dart` when a command is not covered by the CLI. These
 wrappers fail if the pinned SDK is missing. They do not silently use global Flutter.
-Reader `deps`, `check`, and `test` commands are also supported; its library lockfile
-is ignored, so reader dependency setup resolves its declared constraints normally.
-Website and Sphinx checks remain in their own repos.
+Reader `deps`, `check`, and `test` commands also use the pinned SDK and committed
+lockfile. Run the reader browser suite after UI, layout, focus, or worker changes
+as described in `reader/docs/validation.md`.
+
+Website checks use `npm ci && npm run build` in `website/`. Documentation checks
+use `uv sync --locked --extra dev && make build` in `docs/` (Graphviz required).
+
+For a joint reader/client change, validate a local reader using an ignored
+`client/app/pubspec_overrides.yaml`, then remove the override and pin the published
+reader commit in `client/app/pubspec.yaml`. Regenerate the client lock and update
+the workspace's reader and client gitlinks together. The reference check compares
+committed gitlinks and committed dependency files, independently of local overrides.
 
 Server pytest fixtures drop and recreate test tables. The CLI checks for a separate
 local database named `*_test` or `test_*` and locks overlapping CLI server test runs.
@@ -104,8 +116,7 @@ in disjoint files, then use the contract reviewer. Run database tests serially.
 
 `.codex/config.toml` starts the official Dart tooling MCP through `tools/dart-mcp`,
 which uses the pinned SDK. The launcher finds the workspace from the root or a
-nested component directory. Protocol initialization and enumeration of **25 tools**
-were verified from both the root and `client/app`. These include analysis, tests,
+nested component directory. It provides analysis, tests,
 hot reload, widget inspection and runtime-error inspection.
 
 Restart the Codex session to load new project MCP/agent configuration if needed.
@@ -119,45 +130,3 @@ The layout follows [Codex skills](https://learn.chatgpt.com/docs/build-skills),
 and [Dart MCP setup](https://docs.flutter.dev/ai/get-started). FVM's
 [project configuration](https://fvm.app/documentation/getting-started/configuration)
 keeps SDK selection separate from the global toolchain.
-
-## Verified baseline — 2026-10-03
-
-| Scope | Result |
-| --- | --- |
-| Client lockfile | Five transitive versions normalized to the CI SDK; locked installation succeeds |
-| Client formatting | 449 Dart files checked, no changes required |
-| Client analysis | No issues |
-| Client tests | 1,387 passed; 19 skipped |
-| Web bootstrap | Four tests passed |
-| Web build | Release compilation and Wasm dry run succeeded |
-| Reader tests | 93 passed; 21 skipped in the sibling checkout |
-| Server lint/types | Ruff lint and Mypy pass (138 source files) |
-| Server tests | 340 passed; two provider smoke tests excluded |
-| Server formatting | Five pre-existing files need formatting; check correctly fails |
-| Tooling | Eight regression tests, ShellCheck and skill frontmatter validation pass |
-| Dart MCP | Initialized successfully; 25 tools enumerated from root and nested cwd |
-| Local platforms | Flutter doctor finds Android SDK, Xcode, Chrome and macOS target |
-| GitHub CLI | Installed; account sign-in remains pending |
-
-The five server formatting files are `papyrus/models/powersync_demo.py`,
-`tests/api/routes/test_auth_sandbox.py`, `test_powersync_sandbox.py`,
-`tests/integration/test_auth_smoke.py`, and `tests/services/test_auth.py`.
-They were not reformatted as part of tooling setup. Local verification logs are
-ignored under `.local/tooling/`.
-
-Live cross-device PowerSync and external OAuth/SMTP smoke tests were not run.
-Native release builds and Windows/Linux builds were not run. The global Flutter
-SDK remains newer; Flutter doctor may report that PATH mismatch while project
-commands and VS Code use FVM correctly.
-
-The client CI now enforces its lockfile and checks formatting without writing.
-The workspace tooling workflow runs the CLI regressions and ShellCheck on relevant
-pushes and pull requests; it does not require the application submodules or services.
-
-The server README links to auth, acquisition and PowerSync guides absent from
-this checkout. Its existing `.env.example`, tests, services, and
-`docs/opds-relay.md` are usable sources. The client reader dependency is pinned to
-`08a5161b9d00eb73581f74ce087b9ad6c1568ca7`, while the sibling reader checkout is at a
-different revision. Editing it alone does not change client behavior. For a joint
-reader change, use an ignored `client/app/pubspec_overrides.yaml` with a local path
-override during validation, then coordinate a deliberate revision update.

README.md

@@ -80,8 +80,8 @@ Use the workspace CLI from the repository root:
 
 ```bash
 tools/papyrus doctor
-tools/papyrus check client
-tools/papyrus check server
+tools/papyrus deps all
+tools/papyrus check all
 tools/papyrus test client -- test/auth/token_store_test.dart
 tools/papyrus test server -- tests/services/test_sync.py
 ```
@@ -90,4 +90,4 @@ It uses the Flutter version pinned in `.fvmrc` and the server's uv lockfile.
 The same checks and test suites are available as VS Code tasks.
 
 See [development tooling](DEVELOPMENT.md) for the project skills, agent roles,
-Dart MCP integration, setup instructions, and verified baseline.
+Dart MCP integration, and setup instructions.

tools/check_references.py

@@ -0,0 +1,35 @@
+"""Check the committed workspace reader pin against the committed client lock."""
+
+import re
+import subprocess
+from pathlib import Path
+
+
+def git(root: Path, *args: str) -> str:
+    return subprocess.check_output(["git", "-C", str(root), *args], text=True).strip()
+
+
+def check(root: Path) -> None:
+    client = git(root, "ls-tree", "HEAD", "client").split()[2]
+    reader = git(root, "ls-tree", "HEAD", "reader").split()[2]
+    manifest = git(root / "client", "show", f"{client}:app/pubspec.yaml")
+    lock = git(root / "client", "show", f"{client}:app/pubspec.lock")
+    for source, field in [(manifest, "ref"), (lock, "resolved-ref")]:
+        block = re.search(r"(?m)^  papyrus_reader:\n((?:    .*\n?)+)", source)
+        pin = (
+            re.search(rf'{field}:\s*["\x27]?([a-f0-9]{{40}})\b', block[1])
+            if block
+            else None
+        )
+        if pin is None or pin[1] != reader:
+            raise ValueError(
+                f"Committed client {field} must match workspace reader {reader}"
+            )
+    print(f"Committed reader references agree: {reader}")
+
+
+if __name__ == "__main__":
+    try:
+        check(Path(__file__).resolve().parent.parent)
+    except (IndexError, ValueError, subprocess.CalledProcessError) as error:
+        raise SystemExit(f"Reader reference check failed: {error}") from error

tools/papyrus

@@ -12,6 +12,7 @@ from pathlib import Path
 ROOT = Path(__file__).resolve().parent.parent
 CLIENT = ROOT / "client/app"
 SERVER = ROOT / "server"
+READER = ROOT / "reader"
 
 
 def run(args, cwd=ROOT, env=None):
@@ -77,11 +78,18 @@ def checks(component):
                     "--set-exit-if-changed",
                     "lib",
                     "test",
+                    "tool",
+                    "example/lib",
+                    "example/test",
                 ],
-                ROOT / "reader",
+                READER,
             ),
-            ([sdk_command("flutter"), "analyze", "--no-pub"], ROOT / "reader"),
+            (["bash", "tool/build_epub_worker.sh", "--check"], READER),
+            ([sdk_command("flutter"), "analyze", "--no-pub"], READER),
+            ([sdk_command("flutter"), "analyze", "--no-pub"], READER / "example"),
         ]
+    if component == "references":
+        return [([sys.executable, "tools/check_references.py"], ROOT)]
     return [
         (
             [sys.executable, "-m", "unittest", "discover", "-s", "tools/tests", "-v"],
@@ -92,7 +100,11 @@ def checks(component):
 
 
 def check(component):
-    components = ["tooling", "client", "server"] if component == "all" else [component]
+    components = (
+        ["tooling", "references", "client", "reader", "server"]
+        if component == "all"
+        else [component]
+    )
     failed = []
     for item in components:
         for args, cwd in checks(item):
@@ -226,7 +238,7 @@ def main(argv=None):
     )
     quality.add_argument(
         "component",
-        choices=["client", "server", "reader", "tooling", "all"],
+        choices=["client", "server", "reader", "tooling", "references", "all"],
         default="all",
         nargs="?",
     )
@@ -252,7 +264,7 @@ def main(argv=None):
             return test(options.component, args)
         if options.command == "deps":
             selected = (
-                ["client", "server"]
+                ["client", "reader", "server"]
                 if options.component == "all"
                 else [options.component]
             )
@@ -270,7 +282,7 @@ def main(argv=None):
                                 sdk_command("flutter"),
                                 "pub",
                                 "get",
-                                *(["--enforce-lockfile"] if item == "client" else []),
+                                "--enforce-lockfile",
                             ],
                             directory,
                         )

tools/tests/test_papyrus.py

@@ -78,6 +78,27 @@ def test_client_format_check_does_not_write_files(self):
         self.assertIn("--set-exit-if-changed", args)
         self.assertEqual(cwd, cli.CLIENT)
 
+    def test_all_checks_include_reader_and_reference_gate(self):
+        with patch.object(cli, "checks", return_value=[]) as checks:
+            self.assertEqual(cli.check("all"), 0)
+        self.assertEqual(
+            [call.args[0] for call in checks.call_args_list],
+            ["tooling", "references", "client", "reader", "server"],
+        )
+
+    def test_all_flutter_dependencies_enforce_locks(self):
+        with (
+            patch.object(cli, "sdk_command", return_value="flutter"),
+            patch.object(cli, "run", return_value=0) as run,
+        ):
+            self.assertEqual(cli.main(["deps", "all"]), 0)
+        self.assertEqual(
+            [call.args[1] for call in run.call_args_list],
+            [cli.CLIENT, cli.READER, cli.SERVER],
+        )
+        for call in run.call_args_list[:2]:
+            self.assertIn("--enforce-lockfile", call.args[0])
+
     def test_sdk_absent_does_not_fall_back_to_global_flutter(self):
         with (
             tempfile.TemporaryDirectory() as directory,