docs: add upstream submodule cutover plan, README guidance, and AGENTS.md

AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.md
+
+## Scope
+These instructions apply to the entire repository tree rooted at this directory.
+
+## Upstream submodule policy
+- The `upstream/` directory is the canonical location for upstream `devcontainers/cli` TypeScript sources.
+- Do **not** introduce new copies of upstream-owned files at repository root.
+- Keep project-owned implementation and migration work outside `upstream/` unless explicitly updating the submodule pointer.
+
+## Compatibility baseline
+- Treat the pinned `upstream/` submodule commit as the compatibility target.
+- When changing compatibility-sensitive behavior, prefer tests/logging that make the current upstream commit easy to identify.
+
+## Updating upstream
+When asked to update upstream:
+1. Update the submodule pointer in `upstream/`.
+2. Run/adjust parity tests and related fixtures against the new upstream revision.
+3. Keep changes reviewable (submodule bump + project-owned compatibility fixes).
+
+## Pathing expectations
+- Tests, scripts, and docs that need upstream assets should reference paths under `upstream/...` explicitly.
+- Avoid hardcoded assumptions that upstream files exist at repository root.

README.md

@@ -2,6 +2,25 @@
 
 This repository is a Rust port of [devcontainer](https://github.com/devcontainers/cli) CLI. Work in progress, use at own risk.
 
+## Repository layout and upstream compatibility
+
+This repo now tracks the upstream TypeScript implementation as a git submodule at [`upstream/`](./upstream). The pinned submodule commit is the compatibility baseline for this project: when we say we are compatible with upstream, we mean compatible with that exact revision.
+
+- `upstream/`: unmodified upstream devcontainers/cli sources (baseline under test).
+- repository root: project-owned Rust port, migration tooling, compatibility tests, and docs.
+
+When updating upstream, prefer an explicit workflow:
+1. Bump the `upstream/` submodule commit.
+2. Run parity/compatibility tests against the new pinned revision.
+3. Fix regressions in project-owned code.
+4. Merge once CI is green.
+
+If you clone this repository without submodules, initialize them before building/testing:
+
+```bash
+git submodule update --init --recursive
+```
+
 ## Context
 
 A development container allows you to use a container as a full-featured development environment. It can be used to run an application, to separate tools, libraries, or runtimes needed for working with a codebase, and to aid in continuous integration and testing. Dev containers can be run locally or remotely, in a private or public cloud.
@@ -144,6 +163,12 @@ The [example-usage](./example-usage) folder contains some simple shell scripts t
 
 This repository has a [dev container configuration](https://github.com/devcontainers/cli/tree/main/.devcontainer), which you can use to ensure you have the right dependencies installed.
 
+If you have not initialized submodules yet, run:
+
+```sh
+git submodule update --init --recursive
+```
+
 Compile the CLI with yarn:
 ```sh
 yarn

TODO.md

@@ -173,3 +173,55 @@ This balances near-term user value with long-term maintainability.
 - [x] Create a short decision memo: SEA viability vs packager alternatives.
 - [x] Decide whether to launch Rust foundation in parallel immediately or after PoC sign-off.
   - Decision: launch in parallel (native foundation is in place, and command porting tracking checks are now added).
+
+---
+
+## Phase: Upstream submodule cutover (`upstream/`)
+
+### Objective
+Move all vendored upstream TypeScript CLI sources out of repo root and treat `upstream/` (git submodule) as the canonical upstream baseline we target for compatibility.
+
+### 1) Repository layout and ownership
+- [ ] Confirm `upstream/` is the only place where upstream devcontainers/cli code lives.
+- [ ] Remove duplicated upstream-owned files currently checked in at repository root once replacements are wired.
+- [ ] Keep only project-owned integration/porting assets at repository root (Rust code, migration docs, compatibility harness, and project-specific tests).
+- [ ] Add/refresh `.gitmodules` and contributor guidance so updating upstream is intentional and reviewable.
+
+### 2) Build/test path migration
+- [ ] Audit all test fixtures, scripts, and build commands that currently reference root-level upstream paths.
+- [ ] Rewrite references to point at `upstream/...` explicitly (including npm/yarn commands, fixture paths, and script helpers).
+- [ ] Introduce shared path helpers (where practical) to avoid hardcoded duplicate path strings in tests.
+- [ ] Ensure CI jobs execute against `upstream/` sources and fail fast when submodule is missing/uninitialized.
+
+### 3) Compatibility target versioning
+- [ ] Define the compatibility contract as: “this repo targets the exact commit pinned in `upstream/`.”
+- [ ] Expose the pinned upstream commit in test output/logging for traceability.
+- [ ] Add a dedicated CI check that reports diffs/regressions when submodule commit changes.
+- [ ] Create an “update upstream” workflow (bump submodule -> run parity suite -> fix breakages -> merge).
+
+### 4) Documentation updates
+- [ ] Update `README.md` with:
+  - [ ] why `upstream/` exists,
+  - [ ] how to clone/init submodules,
+  - [ ] what to run when submodule is not initialized,
+  - [ ] how compatibility testing maps to the pinned upstream revision.
+- [ ] Add/update root `AGENTS.md` with contributor/agent rules for:
+  - [ ] where upstream code must live (`upstream/` only),
+  - [ ] where project-owned changes should be made,
+  - [ ] how to perform/validate submodule bumps.
+- [ ] Add a short migration note in changelog or docs index once root-level upstream code is removed.
+
+### 5) Execution plan and rollout
+- [ ] Land this as staged PRs to reduce risk:
+  1. [ ] docs + guardrails (`README.md`, `AGENTS.md`, CI checks),
+  2. [ ] path rewrites in tests/scripts,
+  3. [ ] removal of duplicated root upstream code,
+  4. [ ] final parity + cleanup.
+- [ ] Run full parity/integration suite before and after each stage to isolate regressions.
+- [ ] Gate final removal behind green CI across at least one Linux x64 lane.
+
+### Exit criteria
+- [ ] No tests/build scripts depend on root-level upstream copies.
+- [ ] `upstream/` submodule commit is the declared compatibility baseline.
+- [ ] Docs clearly explain contributor workflow for submodule init/update.
+- [ ] CI protects against accidental drift or missing submodule checkout.