Skip to content

Implementation Plan: ANU-9 - Register and Bootstrap the Anuva Bento Repository

References

  • Linear issue: ANU-9
  • Parent change: ANU-8
  • Product Main change docs: Anuva Bento Integration
  • Accepted decision: ADR 0001
  • Repository: anuva-main-video-creator
  • Branch: codex/anu-9-register-and-bootstrap-the-anuva-bento-repositor

Scope and non-goals

Scope

ANU-9 creates the approved private repository boundary and makes it a normal, allowlisted participant in the Anuva Linear, GitHub, CLI, preview, and documentation workflows.

The implementation will:

  1. Create an empty private Shoonya-Game-Technologies/anuva-bento GitHub repository with GitHub Issues and Projects disabled.
  2. Select and record an upstream Bento release tag and commit, then perform one explicitly approved initial history-preserving mirror import before any downstream commit exists.
  3. Clone the private repository to C:\Anuva\dev\anuva-bento, configure origin and upstream, verify the unmodified upstream build/tests, and document provenance.
  4. Add the Bento repository key to Product Main's closed TypeScript allowlist, safe example configuration, docs publisher, tests, and durable engineering documentation.
  5. Add the machine-local repository configuration using docs port 4005, preview URL https://bento1.girishd.com, and aggregate output folder anuva-bento.
  6. Install the normal Anuva repository instructions, implementation/review skills, prompt, templates, MkDocs site, and bootstrap/change documentation in the new repository.
  7. Configure reviewed main protection and rehearse a non-destructive tagged upstream sync branch.
  8. Expand ANU-8's idempotent implementation manifest with the already approved downstream issues, validate it, and dry-run issue creation without creating those issues.

Non-goals

  • Implementing Anuva contracts, editor/player behavior, templates, CMS integration, Unity integration, or Python package changes.
  • Changing Bento product source beyond the files required for repository instructions, documentation, and development workflow bootstrap.
  • Publishing an Anuva Bento package or runtime.
  • Creating the feasibility or production Linear children during ANU-9.
  • Enabling GitHub Issues, GitHub Projects, automatic upstream merges, public collaboration, or Bento self-update behavior.
  • Publishing canonical aggregate documentation.

Current repository behavior

  • Product Main's RepositoryKey schema contains only Product Main, CMS, Python, and Unity.
  • The implementation-manifest schema derives its repository allowlist from that closed key set.
  • Docs publishing has a closed repository label map and one output folder per registered repository.
  • Machine configuration contains no anuva-bento path, label, docs port/URL, or publisher mapping.
  • Product docs describe anuva-bento as an approved target whose bootstrap is pending.
  • GitHub reports that Shoonya-Game-Technologies/anuva-bento does not currently exist.
  • No Linear implementation issue can target anuva-bento until the repository label and CLI/configuration key both exist.

Planned changes

Acceptance check Code or system area Test/evidence Docs
Private independent downstream exists GitHub organization repository settings; one-time initial import; local clone/remotes gh repo view; visibility/fork/default-branch checks; tag/SHA/ancestry/remotes Provenance, repository overview, ADR/registry status
Upstream baseline is unmodified and reproducible Local anuva-bento clone before downstream bootstrap commit Exact release tag/SHA; install, build, applicable upstream tests; clean source diff Provenance and ANU-9 ImplementationLog/CompletionReport
Product Main recognizes Bento without arbitrary repository strings src/schemas/development-config.ts, implementation manifest schema consumers, src/docs-publisher/index.ts Typecheck; config/manifest/context/doctor/publisher tests; invalid-key rejection Anuva CLI, environment, registry, workflow docs
Machine configuration resolves Bento %APPDATA%\Anuva\development.yaml Configuration parse; anuva context show; anuva doctor; port uniqueness Development Environment and safe example
Linear has exactly one repository label Linear workspace Repository label group Read-back through a Bento-labeled test/dry-run issue context; no manual status changes Linear Workflow and ANU-9 log
Branch-specific Bento preview works Bento MkDocs config, machine tunnel route, Cloudflare Access domain Local 4005; exact HTTPS route; anuva docs ensure/wait/links; strict build/index validation Cloudflare setup and Bento bootstrap docs
New repository has the normal Anuva workflow AGENTS.md, .agents/skills/anuva, prompt, templates, process docs, launcher Skill validation; explicit/implicit invocation checks; CLI context and dry runs Bento process, prompt, skill, templates, change index
Protected downstream delivery and upstream sync are safe GitHub branch protection; origin/upstream; disposable sync rehearsal branch Protection read-back; no direct main push; upstream tag merge rehearsal; ref comparison; rehearsal branch cleanup Upstream sync/release runbook
ANU-8 handoffs are executable Product Main ImplementationIssues.manifest.json and issue registry JSON/schema validation; dependency-order test; CLI dry run reuses ANU-9 and proposes only approved children Implementation Issues and Progress
Full bootstrap evidence is durable Product Main and Bento change folders Strict builds, index validation, exact previews, PR/report links ImplementationLog and CompletionReport in both repositories

Product Main code and test changes

Closed repository allowlist

  • Add anuva-bento to RepositoryKey in src/schemas/development-config.ts.
  • Keep z.enum(repositoryKeys) validation for services, manifests, publisher mappings, and all repository-aware commands. Do not replace it with an arbitrary string schema.
  • Add Anuva Bento to the docs-publisher label map.
  • Confirm context discovery, Linear repository matching, issue creation, doctor, docs, PR, and publisher operations continue deriving from the same closed key set.

Configuration

Add this safe example and machine-local entry:

repositories:
  anuva-bento:
    path: C:\Anuva\dev\anuva-bento
    github: Shoonya-Game-Technologies/anuva-bento
    linearRepositoryLabel: anuva-bento
    docsPort: 4005
    docsUrl: https://bento1.girishd.com
    baseBranch: main

publisher:
  outputFolders:
    anuva-bento: anuva-bento

Machine-local configuration is never committed. Its exact absolute target is %APPDATA%\Anuva\development.yaml.

Tests

  • Extend the shared fixture configuration with anuva-bento.
  • Verify all registered repository ports, URLs, and publisher folders remain unique.
  • Add manifest acceptance for anuva-bento and continued rejection of unknown repository names.
  • Update publisher, doctor, context, and repository iteration expectations.
  • Add an integration fixture proving a Bento-labeled issue resolves to the new repository.
  • Run bun run typecheck, the complete Bun test suite, relevant focused tests, CLI help/context/doctor checks, strict MkDocs, recursive index validation, and launcher reinstall/verification.

GitHub downstream bootstrap

Exact target and safety boundary

  • Target: Shoonya-Game-Technologies/anuva-bento
  • Visibility: private
  • GitHub Issues: disabled
  • GitHub Projects: disabled
  • Default branch after import: main
  • Initial source: one verified release tag and commit from https://github.com/nyblnet/bento.git

Before creation, recheck that the target does not exist. Before the initial mirror push, recheck that the target has no downstream commits. Perform the mirror push exactly once. After that point, mirror pushes are permanently forbidden because they can overwrite downstream refs.

Use a verified temporary bare/mirror clone outside repository working trees. Resolve and inspect the absolute temporary directory before deleting it. Clone the completed private downstream normally at C:\Anuva\dev\anuva-bento.

Configure:

origin    https://github.com/Shoonya-Game-Technologies/anuva-bento.git
upstream  https://github.com/nyblnet/bento.git

Normal operation fetches from upstream and pushes only reviewed feature or sync branches to origin.

Unmodified baseline gate

Before adding any Anuva file:

  • record the selected release name, tag, commit SHA, release date, and upstream repository URL;
  • verify HEAD, the selected tag, and ancestry;
  • install with the upstream-declared package manager and lockfile behavior;
  • run the upstream build and applicable tests documented by that exact revision;
  • verify the expected self-contained Bento Slides artifact; and
  • record warnings, skipped tests, and environmental limitations.

Failure stops ANU-9 before downstream workflow bootstrap.

Protection and sync rehearsal

Protect main against deletion and force pushes and require pull-request delivery. Do not require nonexistent status-check names.

Create a disposable rehearsal branch from protected main, fetch upstream tags, merge or no-op merge the selected upstream tag using the documented strategy, run the baseline checks, compare refs, and verify no downstream ref is replaced. Delete only the verified rehearsal branch after its evidence is captured.

New repository workflow bootstrap

The first downstream commit contains process and documentation only:

  • root AGENTS.md with the Bento ownership boundary;
  • standard implementation issue discovery, planning, review, and docs-preview skills adapted for anuva-bento;
  • an implementation prompt and templates for ImplementationPlan.md, ImplementationLog.md, and CompletionReport.md;
  • mkdocs.yml, docs/index.md, and an index in every docs directory;
  • repository overview, provenance, architecture, development workflow, Anuva CLI bootstrap, upstream-sync/release, security/license, and ANU-9 change pages; and
  • explicit prohibition on Anuva product implementation in this bootstrap.

Because no normal downstream branch can exist before the repository itself exists, the one-time history import is the only bootstrap exception. The first Anuva-authored downstream commit and every later change use a reviewed branch and PR. Direct merge to protected main is not authorized.

Admin prerequisites and user actions

The following organization-level configuration cannot be inferred or silently performed:

  1. Linear: create exactly one anuva-bento label inside the existing Repository label group. Do not change issue statuses or enable automatic transitions.
  2. Cloudflare Tunnel: add bento1.girishd.com -> http://127.0.0.1:4005 to the remotely managed anuva-machine1 tunnel.
  3. Cloudflare Access: add bento1.girishd.com to the existing protected Development application with the same approved access policy as the other repository preview hostnames.

At implementation time, Codex will present each exact mutation. If the current authenticated tools cannot perform an admin action safely, the user will perform the documented UI step and Codex will verify the result before continuing.

Manifest expansion

After Product Main code, live configuration, Linear label, and downstream workflow verification pass, expand the existing ANU-8 manifest rather than creating an unrelated file.

  • Preserve main-bento-bootstrap so the idempotent operation reuses ANU-9.
  • Add the approved Bento spike, Bento runtime, Bento editor/templates, CMS v2, CMS editor/AI, Unity player, and Python package issues.
  • Encode the approved dependency graph from ImplementationIssues.md.
  • Validate JSON and schema locally.
  • Run anuva linear change create-implementation-issues <manifest> --dry-run.
  • Require a later, separate Product Main approval before confirming creation.

ANU-9 does not confirm that expanded mutation.

Contracts and dependencies

  • ANU-8 and its accepted ADR remain the source of product scope.
  • ANU-9 owns only repository/process bootstrap and Product Main harness changes.
  • The selected upstream tag/SHA and license/notices are immutable provenance inputs for later Bento issues.
  • anuva-bento must be present in GitHub, Linear, the Product Main allowlist, and machine configuration before the expanded manifest may target it.
  • The Bento feasibility spike remains the first product implementation child.
  • No production child may start without the later Product Main go/no-go decision.

Migration, rollback, and failure handling

  • If the GitHub target appears between verification and creation, stop and inspect it; never overwrite or import into an ambiguous repository.
  • If the initial import partially succeeds, inspect remote refs before retrying. Never repeat a mirror push after any downstream commit exists.
  • If upstream baseline checks fail, retain evidence and stop before adding Anuva files.
  • If Product Main code/config tests fail, do not update the installed launcher or use the expanded manifest.
  • If the Linear label or Cloudflare route is unavailable, leave the corresponding integration unverified and keep ANU-9 In Progress.
  • Machine-local configuration changes are recoverable by restoring the exact pre-edit file; no secrets are added.
  • Downstream process commits can be reverted through a reviewed PR without altering imported upstream history.
  • Repository deletion, visibility change, destructive ref rewrite, or broad Cloudflare/Linear cleanup is outside this plan and requires a separate explicit decision.

Verification commands

Product Main planned checks:

bun run typecheck
bun test
anuva docs validate-indexes --repository current
mkdocs build --strict
.\scripts\install-anuva-cli.ps1
anuva context show --json
anuva doctor
anuva linear change create-implementation-issues "<absolute-manifest>" --dry-run
git diff --check
git status --short

Downstream commands will be finalized from the selected upstream revision before execution. The minimum evidence includes:

git remote -v
git tag --points-at <selected-sha>
git merge-base --is-ancestor <selected-sha> main
<upstream install command>
<upstream build command>
<upstream test commands>
anuva context show --json
anuva docs validate-indexes --repository current
mkdocs build --strict

GitHub, Linear, branch protection, preview, network, license, and manifest read-backs are recorded in the ImplementationLog and CompletionReport with secrets redacted.

Risks and open questions

  • Proposed preview allocation: approve port 4005, bento1.girishd.com, and aggregate folder anuva-bento.
  • Upstream baseline: select the latest suitable tagged release at execution time and record its exact SHA; do not hardcode a moving branch.
  • Admin access: Linear label and Cloudflare tunnel/Access configuration may require user UI actions if no safe authenticated admin tool is available.
  • Branch protection: organization plan/settings may constrain exact protection fields; preserve the required PR/no-force-push/no-delete outcome and record any supported equivalent.
  • Upstream tests: the exact revision may expose environment-specific or long-running checks; skipped checks require explicit evidence and review.
  • Private package access: intentionally deferred to the later runtime-contract issue.

Approval

Status: Approved.

  • Reviewed by: Girish
  • Approved at: 2026-07-24 06:25 UTC
  • Approval scope: The plan as written, including Product Main allowlist and test changes, private GitHub repository creation and initial history import, machine configuration, proposed port/hostname allocation, downstream workflow bootstrap, admin prerequisites, upstream verification, and manifest dry run.
  • Remaining boundaries: Exact external mutations must still identify their targets and respect tool approval or user-admin prerequisites. Expanded downstream Linear issue creation is not authorized by this approval.