first commit

docs/UPSTREAM.md

@@ -0,0 +1,134 @@
+# Oxi upstream policy
+
+RustBox is derived from `c0h1b4/oxi`. `UPSTREAM_BASE` contains the exact Oxi commit whose backend changes have been consumed by RustBox.
+
+RustBox uses a flat Cargo layout, while Oxi uses a `backend/` subtree. The sync tooling therefore treats Oxi as a source upstream and maps its backend paths into RustBox rather than reintroducing the Oxi directory layout.
+
+## Path mapping
+
+Examples:
+
+```text
+Oxi backend/Cargo.toml          -> RustBox Cargo.toml
+Oxi backend/Cargo.lock          -> RustBox Cargo.lock
+Oxi backend/rust-toolchain.toml -> RustBox rust-toolchain.toml
+Oxi backend/src/...             -> RustBox src/...
+Oxi backend/migrations/...      -> RustBox migrations/...
+Oxi backend/tests/...           -> RustBox tests/...
+Oxi backend/examples/...        -> RustBox examples/...
+Oxi backend/docs/...            -> RustBox docs/...
+```
+
+RustBox-owned `src/web/` has no automatic mapping from the Oxi frontend.
+
+## Configure the upstream
+
+A release archive does not contain `.git`. Initialize the RustBox repository once:
+
+```bash
+git init
+git add .
+git commit -m "RustBox 0.0.1 baseline"
+./scripts/setup-upstream.sh
+```
+
+The script adds:
+
+```text
+upstream-oxi -> https://github.com/c0h1b4/oxi.git
+```
+
+and fetches Oxi history/tags.
+
+## Inspect a newer Oxi state
+
+```bash
+./scripts/oxi-status.sh
+```
+
+or inspect a specific Oxi ref:
+
+```bash
+./scripts/oxi-status.sh upstream-oxi/main
+./scripts/oxi-status.sh <tag-or-commit>
+```
+
+The report separates:
+
+1. Oxi `backend/` changes that can be mapped into RustBox;
+2. Oxi `frontend/` changes that require a manual UI port;
+3. other Oxi root-level changes that require manual review;
+4. upstream commits since `UPSTREAM_BASE`.
+
+## Advance the consumed Oxi backend state
+
+```bash
+./scripts/sync-upstream.sh
+```
+
+The operation:
+
+1. requires a clean RustBox Git worktree;
+2. fetches `upstream-oxi`;
+3. verifies that the target descends from the recorded `UPSTREAM_BASE`;
+4. creates a `sync/oxi-*` review branch;
+5. generates the Oxi backend delta from `UPSTREAM_BASE` to the target;
+6. rewrites only patch metadata so `backend/<path>` becomes `<path>`;
+7. applies the mapped delta with Git three-way merge support;
+8. does not import Oxi frontend sources;
+9. records the target as a pending sync inside Git metadata;
+10. deliberately leaves `UPSTREAM_BASE` unchanged until the maintainer finishes review.
+
+Conflicts are expected when Oxi and RustBox changed the same functionality. Resolve them in the flat RustBox paths, keeping RustBox-specific behavior where required.
+
+After resolving backend conflicts and porting any relevant UI behavior, finish the sync:
+
+```bash
+./scripts/finish-upstream.sh
+```
+
+If Oxi changed its frontend or root-level files, the finish step refuses to advance the baseline until you explicitly acknowledge those reviews:
+
+```bash
+./scripts/finish-upstream.sh --ui-reviewed --root-reviewed
+```
+
+The finish step runs the RustBox release build gate and only then stages the new `UPSTREAM_BASE`. Review `git status` and commit the sync. `--skip-build` exists for exceptional local workflows, but CI should still run the full gate before merge.
+
+If the sync is rejected, discard the review branch; the main branch and its `UPSTREAM_BASE` remain unchanged.
+
+## Port one Oxi feature
+
+For a useful Oxi commit that should be brought in before a full baseline update:
+
+```bash
+./scripts/oxi-port-commit.sh <oxi-commit>
+```
+
+This creates `port/oxi-<sha>` and maps only the backend portion of that single commit. It intentionally does not change `UPSTREAM_BASE`, because RustBox has not consumed the complete Oxi history up to that revision.
+
+When a later full sync includes a previously ported feature, Git may report that some hunks are already present; review those conflicts instead of duplicating the code.
+
+## UI policy
+
+Oxi frontend source is never copied into RustBox. For a new Oxi feature that includes frontend work:
+
+- consume or port the backend/API changes;
+- inspect the corresponding Oxi frontend diff to understand behavior;
+- implement that behavior in RustBox `src/web/`;
+- keep the same-origin RustBox API/UI model;
+- do not add `.ts` or `.tsx` sources.
+
+## RustBox-owned boundaries
+
+These areas require explicit review and should not be replaced blindly by upstream changes:
+
+- `src/web/`;
+- `src/ui.rs`;
+- RustBox UI routing and same-origin behavior;
+- RustBox ManageSieve integration;
+- `dev.sh`;
+- native packaging/release scripts;
+- RustBox branding and documentation.
+
+The goal is to keep following Oxi protocol/backend improvements without restoring its split frontend/backend repository structure.