docs: establish BlockWire boundaries and deployment baseline

AGENTS.md

@@ -0,0 +1,37 @@
+# BlockWire agent instructions
+
+## Read first
+
+Read [README.md](README.md), [ARCHITECTURE.md](ARCHITECTURE.md), [PROJECT_STATUS.md](PROJECT_STATUS.md), and [DEPLOY.md](DEPLOY.md). Treat [STATUS.md](STATUS.md) as dated historical evidence, not automatic proof of the current runtime.
+
+## Product and visibility boundaries
+
+This public repository owns the BlockWire client: web/PWA and the Tauri client source. The canonical remote is `stormchaserog/blockwire`. Block Social, Jungle Ops, and the WCLAW website are separate products and must not be copied here.
+
+The bot gateway, push gateway, and deployment infrastructure have separate private repositories. Do not copy their operational files, host addresses, access details, credentials, or private implementation into this public repo. Document only the public interfaces already intended for client use. Preserve the source attribution and license files for the Sable-derived client.
+
+## Source and release identity
+
+The current default and Vercel production branch is `dev`; the production project is `blockwire` and the public domain is `blockwire.chat`. Use task branches and PRs against `dev`. Do not rename the production branch or retarget deployments as incidental cleanup.
+
+Check current commits and open PRs before editing. Do not bulk-delete stale-looking branches or overwrite another contributor's work. Release and dependency PRs must be reconciled separately from a product-boundary change.
+
+## Verification
+
+Use the toolchain constraints in `package.json` and the setup in `mise.toml`. CI installs with `pnpm install --frozen-lockfile`; see `.github/actions/setup/action.yml`. The existing npm alternative and lockfile constraints are described in `DEPLOY.md`.
+
+For application changes, run the relevant CI checks: formatting, lint, typecheck, tests, and build. Use the specific scripts in `package.json`. Do not rewrite unrelated code to make a documentation check pass. For documentation-only changes, validate changed-file formatting, relative links, source facts, and `git diff --check`; describe the limits of that verification.
+
+Do not fabricate a changeset for a user-facing release when the change is internal documentation. Follow the repository's existing changeset workflow and its documented internal-change handling.
+
+## Deployment invariants
+
+- Build and deploy from the repository root with `dist` as the output directory. Never create a Vercel project by deploying from inside generated `dist/`.
+- Preserve Matrix delegation files and SPA routing. Do not add an `/index.html` redirect that breaks service-worker precaching.
+- Production-target deployment and custom-domain assignment are separate checks. Follow `DEPLOY.md` and verify the actual domain before declaring a release live.
+- Preserve the previous serving deployment as a rollback reference; web rollback does not restore homeserver, bot, push, or native-client state.
+- Test service-worker-sensitive changes in a fresh profile or with deliberate cache handling; do not mistake cached assets for release verification.
+
+## Documentation maintenance
+
+Update `PROJECT_STATUS.md` with a dated, evidenced release baseline when a release changes it. Update `ARCHITECTURE.md` when service boundaries change. Keep private operational detail in the private infrastructure runbook. Distinguish a built feature, a historically tested feature, and a freshly verified production behavior.

ARCHITECTURE.md

@@ -0,0 +1,38 @@
+# BlockWire architecture
+
+BlockWire is a Matrix-based messaging client. This public repository contains the React/TypeScript/Vite web application and Tauri client source. Its independently operated services remain in separate private repositories.
+
+## Components and ownership
+
+| Component                     | Source / configuration                                        | Boundary                                                                 |
+| ----------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| Web client                    | `src/`, `package.json`, `vite.config.ts`                      | This repository; static output served by Vercel                          |
+| Product configuration         | `config.json`                                                 | Public branding, homeserver discovery, and client endpoint configuration |
+| Native client                 | `src-tauri/`                                                  | This repository; separate native build/release lifecycle                 |
+| Matrix discovery              | `public/.well-known/matrix/`, build copy rules, `vercel.json` | Public delegation consumed by clients                                    |
+| Homeserver and infrastructure | Private `blockwire-infra` repository                          | Deployment and data operations; private runbook owns operational details |
+| Bot platform                  | Private `blockwire-botgw` repository                          | Bot API and registration/directory/interaction backend                   |
+| Push delivery                 | Private `blockwire-push` repository                           | Web-push delivery service                                                |
+
+The public client declares Matrix SDK dependencies and uses the configured homeserver. It does not own the backend database lifecycle. Backend topology, access details, and recovery procedures belong in the private infrastructure runbook.
+
+## Request and release flow
+
+1. Vercel serves the client at `blockwire.chat` from a build of this repository.
+2. Public Matrix delegation and product configuration identify the homeserver/services.
+3. The client authenticates and communicates using the configured Matrix interfaces; bot/push/call services have their own runtime owners.
+4. The service worker caches client assets. A deployed build is not necessarily the version already cached by a user's installed app.
+
+`vercel.json` explicitly serves delegation documents as JSON and routes application paths to `index.html`. `vite.config.ts` is responsible for copying required public resources because the app uses a customized asset pipeline. Output is `dist` from the repository root. See [DEPLOY.md](DEPLOY.md) for the known path, alias, and precache traps.
+
+## Toolchain and verification
+
+`package.json` declares the Node runtime constraints, pnpm version, and application scripts; `mise.toml` configures CI tool setup. `.github/workflows/quality-checks.yml` runs formatting, lint, type checking, unused-code analysis, tests, and a build. Native and end-to-end workflows are separate. A web build does not verify actual device push, background calls, or native store readiness.
+
+## Other products
+
+Block Social is a different application. Jungle Ops and the WCLAW website are also separate. Shared ownership or token/community references do not justify copying their code into this client or exposing private service internals here. Any necessary integration should have an explicit public API contract and independently reviewable changes in the owning repositories.
+
+## Recovery
+
+Keep a known serving web deployment before changing the production domain assignment. Verify Matrix delegation, login, navigation, and cache/update behavior after an authorized release. Backend or native rollback is a separate operation with separate compatibility checks; switching the web deployment does not undo server data or gateway changes.

PROJECT_STATUS.md

@@ -0,0 +1,39 @@
+# BlockWire project status
+
+Metadata verified at `2026-09-24T02:01:54.398875+00:00`. Maintainer: `stormchaserog`.
+
+## Verified source and deployment baseline
+
+| Item                                      | Observation                                         |
+| ----------------------------------------- | --------------------------------------------------- |
+| Canonical source                          | `stormchaserog/blockwire` (public)                  |
+| Default / Vercel production branch        | `dev`                                               |
+| Source head at observation                | `142a4f9510e35e80eade591f12a3a1c7517da687`          |
+| Vercel project / root                     | `blockwire` / repository root                       |
+| Output directory in source                | `dist`                                              |
+| Branch protection reported                | `dev`: true                                         |
+| Open PRs before this documentation change | 18, including dependency updates and release PR #37 |
+
+| Domain           | Serving commit                             | State |
+| ---------------- | ------------------------------------------ | ----- |
+| `blockwire.chat` | `142a4f9510e35e80eade591f12a3a1c7517da687` | READY |
+
+The Vercel custom-domain assignment was resolved to the serving deployment; the source commit matches the observed `dev` head. Internal deployment/account identifiers and backend operational details are intentionally kept out of this public document. Operators must record the exact serving deployment in the private release record before a cutover.
+
+This pass verified metadata and source relationships, not authenticated member journeys, bot behavior, device push, calls, native builds, or backend health. READY does not prove those behaviors work.
+
+## Existing implementation and historical evidence
+
+The source includes the messaging client, bot interaction UI, push integration, service-worker update handling, and Tauri project. [STATUS.md](STATUS.md) records tests and caveats as of 2026-08-06. Its statements about what was live are historical observations and were not rerun in this pass.
+
+## Outstanding verification and cleanup
+
+1. Reconcile the historical push, real-app bot-button, and native iOS follow-ups against current device/runtime evidence.
+2. Review dependency PRs and release PR #37 individually; do not merge them merely to clean up the branch list.
+3. Verify custom-domain assignment on every release. [DEPLOY.md](DEPLOY.md) records that a production deploy alone may leave the domain on an older build.
+4. Review the accidental legacy `dist` Vercel project and the unlinked `blockwire-app` project for retirement only after checking their consumers. Neither should become a second canonical source repository.
+5. Keep private service repos independent and document any changed API contracts with their owners.
+
+## Next step and rollback boundary
+
+Land the reviewed documentation baseline without changing production configuration. For the next authorized release, refresh the private serving-deployment record, validate the intended build, and keep the previous compatible deployment available. Confirm a fresh browser receives the intended assets and delegation responses after changing the domain assignment. Roll back the client only when compatible with the running services; backend state and native releases are separate.

README.md

@@ -28,7 +28,16 @@ gateway. Users never need to know or care what Matrix is.
 | Push gateway | Web push delivery, private repo |
 | Infrastructure | Homeserver and deploy config, private repo |
 
-Current status and what's next: **[STATUS.md](./STATUS.md)**.
+## Project documentation
+
+- [AGENTS.md](./AGENTS.md): repository scope and working rules.
+- [ARCHITECTURE.md](./ARCHITECTURE.md): client components and service boundaries.
+- [PROJECT_STATUS.md](./PROJECT_STATUS.md): dated source/deployment baseline and next steps.
+- [STATUS.md](./STATUS.md): historical operational handoff, with original verification dates.
+- [DEPLOY.md](./DEPLOY.md): deployment procedure and known traps.
+
+Maintainer: `stormchaserog`. This is the public client repository, not a home for
+private infrastructure, Block Social, Jungle Ops, or WCLAW website code.
 
 ## Development
 

STATUS.md

@@ -1,5 +1,7 @@
 # BlockWire — where we left off
 
+> Historical handoff. Use [PROJECT_STATUS.md](PROJECT_STATUS.md) for the latest dated source/deployment baseline. Claims below retain their original verification date and are not re-certified by a documentation update.
+
 Last updated: 2026-08-06
 
 > Operational details (addresses, how to reach each box, deploy commands) are in