docs: add root architecture reference

README.md

@@ -141,6 +141,7 @@ Push is early software. Please read the [security policy](SECURITY.md) before
 reporting a vulnerability. Bug reports, ideas, and pull requests are welcome.
 
 - [Contributing](CONTRIBUTING.md)
+- [Architecture](ARCHITECTURE.md)
 - [Code of conduct](CODE_OF_CONDUCT.md)
 - [Security policy](SECURITY.md)
 - [MIT license](LICENSE)

docs/contributing.md

@@ -37,7 +37,9 @@ cargo test --locked
 | Durable user questions | `src/approval.rs`, `src/history.rs` |
 | Production diagnostics | `src/doctor.rs`, `src/audit.rs` |
 
-Read [architecture](architecture.md) before changing state, crash recovery,
+Read the
+[architecture](https://github.com/owainlewis/push/blob/main/ARCHITECTURE.md)
+before changing state, crash recovery,
 channel cursors, session ownership, scheduling, or delivery semantics.
 
 ## Documentation workflow

docs/core-system/design.md

@@ -5,7 +5,9 @@
 !!! warning "Historical record"
 
     This file preserves the approved design and rollout sequence. It is not a
-    current roadmap. See [Architecture](../architecture.md) for shipped behavior.
+    current roadmap. See the
+    [architecture](https://github.com/owainlewis/push/blob/main/ARCHITECTURE.md)
+    for shipped behavior.
 
 **Author:** Owain Lewis  **Date:** 2026-07-11
 

docs/getting-started.md

@@ -181,4 +181,4 @@ a Telegram- or Slack-only Linux host.
 - [Configure both channels and per-thread routes](configuration.md)
 - [Create a manual or scheduled job](jobs.md)
 - [Inspect every CLI command](reference/cli.md)
-- [Understand durable state and recovery](architecture.md)
+- [Understand durable state and recovery](https://github.com/owainlewis/push/blob/main/ARCHITECTURE.md)

docs/index.md

@@ -103,7 +103,7 @@ tools, skills, and authentication. Chats preserve configured agent permissions;
 Codex and Claude jobs bypass interactive permissions so scheduled work can
 finish without an operator.
 
-[See the full architecture](architecture.md){ .push-inline-link }
+[See the full architecture](https://github.com/owainlewis/push/blob/main/ARCHITECTURE.md){ .push-inline-link }
 
 </section>
 
@@ -179,7 +179,7 @@ finish without an operator.
 | choose backend permissions safely | [Permissions and security](security.md) |
 | keep Push online after logout or reboot | [Run as a service](services.md) |
 | inspect commands and outputs | [CLI reference](reference/cli.md) |
-| understand or extend the code | [Architecture](architecture.md) and [contributing](contributing.md) |
+| understand or extend the code | [Architecture](https://github.com/owainlewis/push/blob/main/ARCHITECTURE.md) and [contributing](contributing.md) |
 
 !!! note "Canonical source"
 

mkdocs.yml

@@ -58,7 +58,7 @@ nav:
       - Run as a service: services.md
   - Reference:
       - CLI commands: reference/cli.md
-      - Architecture: architecture.md
+      - Architecture: https://github.com/owainlewis/push/blob/main/ARCHITECTURE.md
   - Develop:
       - Contributing: contributing.md
       - Product strategy: strategy.md

tests/docs.rs

@@ -6,7 +6,7 @@ use pulldown_cmark::{Event, Options, Parser, Tag, TagEnd};
 #[test]
 fn local_documentation_links_resolve() {
     let root = Path::new(env!("CARGO_MANIFEST_DIR"));
-    let mut markdown = vec![root.join("README.md")];
+    let mut markdown = vec![root.join("README.md"), root.join("ARCHITECTURE.md")];
     collect_markdown(&root.join("docs"), &mut markdown);
 
     let mut broken = Vec::new();