# Succinix — Agent & Design Guidelines

Design rules for anyone (human or AI agent) modifying this project. English text is normative; Chinese is explanatory.

## Design Spec

- **UI language: English only.** Every character rendered to the user (splash, system info, help, command output, errors, self-test, port/db info) must be English. Code comments may stay Chinese (developer docs), but never terminal-facing strings.
- **No emoji.** Emoji and pictorial glyphs are banned everywhere in the UI (`✅❌🎉🚀🔥…`). Use ASCII status markers only: `[  OK  ]` / `[ FAIL ]` / `[SKIP]`. Replace the unicode ellipsis `…` with `...` in user-facing text. **Scope: terminal/UI text and code output** — documentation (`docs/*.md`) may use status glyphs (`✅`/`⚠️`/`❌`) in tables where they aid readability; the static self-check below scans `src/` and `index.html` only.
- **Theme: dark amber (no green).** `background: #0a0a0a`, foreground warm white `#d6cfc4`, cursor/accent dark orange `#c2702a`, selection `#3a2a1a`. ANSI palette is a muted warm set: red `#c0543a`, yellow/gold `#c98a2e`, green dark olive `#7a8a5a`, dim gray `#6b6560`, bright variants one step lighter. The `[  OK  ]` marker and ASCII-art splash use amber (`\x1b[33m`), not green. Never introduce a `GREEN` emphasis constant.
- **Font: JetBrains Mono.** Fonts are bundled locally via `@fontsource/jetbrains-mono` (no CDN). xterm `fontFamily`: `'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, Consolas, monospace`.
- **Professional and restrained; not toy-like.** Follow Linux conventions: prompt `guest@succinix:~$ `, `bash: xxx: command not found`-style errors, gray `[exit N]` markers, `PID  STATUS  COMMAND` ps table, English `unknown command: xxx`.

## Technical Constraints (do not change)

- **File RPC channel:** `/cmd.json` → `/result-<id>.json`, one independent result file per request. Do not revert to a single shared result file.
- **Unified routing:** commands starting with `node|npm|npx` go to a real Node child process; everything else goes to the Lifo sandbox. Do not change this split.
- **Dev server:** Vite on port `7892` with `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: credentialless` (WebContainer requires cross-origin isolation).
- **tinbase:** must start with `--engine wasm`（no `--memory` — data persists in the workspace snapshot; the in-browser install timeout is host-side `{ timeout: 120000 }`, client wait `150000`).
- **`scripts/build-host.mjs`:** `@lifo-sh/ui` stays external. Produces two in-container bundles: `public/host.js` (lightweight host daemon — RPC loop, process table, node subprocesses) and `public/lifo-core.js` (the ~1 MB `@lifo-sh/core` kernel, loaded lazily via `import('./lifo-core.js')` on first Lifo command). Rebuild with `node scripts/build-host.mjs` after touching files under `src/engine/host/`, `src/engine/host-procs.ts`, or `src/engine/lifo-core.ts`.

## WebContainer-Native Architecture (normative)

- **WebContainer is the execution world and capability source of truth.** Lifo is not a browser-side imitation: `lifo-core.js` is dynamically imported by `node host.js` inside WebContainer, and its `/workspace` mount delegates to the same virtualized `node:fs` tree used by real Node and Python runtimes.
- **Extend the execution world; do not assemble a parallel browser-side Linux.** New shells, commands, packages, services, runtimes, editors, TUIs, and third-party extensions belong in the WebContainer/Lifo userland whenever physically possible. They must share the existing filesystem, cwd/env, instance, process, service, package, persistence, and capability models.
- **The browser is the control/device plane.** Browser code may boot WebContainer, render xterm, collect keyboard/resize events, expose unavoidable Web APIs, and transport data across the browser↔WebContainer boundary. That transport must stay thin and must not create a second command implementation, filesystem, process table, service registry, package state, or editor state outside the execution world.
- **Standard Unix names are execution-world commands.** Do not add new browser-local implementations that shadow standard commands. Browser-only management stays under the `succinix ...` namespace; v0.7 moves existing standard-name local handlers into Lifo/host adapters where necessary.
- **Interactive applications use Lifo's native terminal seam.** `@lifo-sh/core` exports `ITerminal` and exposes command input/raw mode through `CommandContext.stdin` and `setRawMode`; its internal `TerminalStdin` backs that public command contract. Succinix must connect browser xterm to that in-WebContainer seam through thin terminal transport and preserve streaming output plus live `cols`/`rows`; it must not implement `vi`, `nano`, or third-party TUIs as parallel browser applications. Third-party packages must not import the non-root-exported `TerminalStdin` implementation directly.
- **Built-in and third-party interactive tools follow the same path.** `vi`, `nano`, future REPL/TUI tools, and third-party Lifo packages run inside the WebContainer userland, use the same terminal-session protocol and lifecycle, and appear in the same process/capability views. No special UI-only package class is allowed.

## Cordis Single-Track (0.7.0+)

- `@succinix/engine@0.7.0` is one Cordis plugin. Its root export is
  `{ name: 'succinix', apply, Config }`; there is no separate SDK line or
  `plugin-*` companion package.
- Normal consumer plugins explicitly inject only the dsh services they use:
  `fs`, `sandbox`, `terminals`, and `sessionPersistence`. Optional services are
  discovered with `ctx.get('<key>', false)`, never implicit globals or top-level
  `ctx.mixin`.
- `ctx.get('succinix', false)` is the same-context host seam for lifecycle,
  instances, ports, services, snapshots and the default executor. It does not
  replace the four dsh services. See `docs/SDK.md` and the executable
  `docs/cordis-contract.md`.
- Only `src/plugin/` may import `cordis`; `src/engine`, `src/terminal`,
  `src/instance`, `src/persist`, and `src/services` stay Cordis-free.
- `./terminal` and `./instance` are not package exports. Use
  `host.terminal.open(...)` and `host.ensureInstance(...)` after getting the
  host seam.
- Server and command callbacks are not configuration fields. Subscribe through
  `host.onServerReady`, `host.onServerClosed`, or typed `succinix/*` events.
- The page-level HostManager is a module singleton. Fiber reload must not
  restart it; only `shutdown()` or page unload performs hard host teardown.
- Rebuild with `node scripts/build-engine-package.mjs` after touching
  `src/plugin/`; it regenerates `packages/engine/assets/sha256.json` and checks
  the package exports.
- Current integration documents are `docs/SDK.md`, `docs/PLUGIN.md`,
  `docs/MIGRATION.md`, and `docs/cordis-contract.md`.
- Publishing and deprecating old versions are release-owner actions. Do not
  publish unless the user explicitly requests it.

## Explicitly Not Implemented (do not force)

Browser-environment limits are accepted as-is. Do not build simulations with no real value; if a capability cannot genuinely work, it is omitted or clearly degraded:

- **Multi-user / login / permission isolation.** Organizational isolation only (available in embed mode): directories, state, and process views are partitioned per instance/user (`?instance=<id>` / `?user=<id>`); this is **not a security boundary** — there is no real kernel or permission bits. A login ritual without real isolation still has no value; `guest` remains the only user of the standalone app, and permission-bit / `chmod` semantics stay out.
- **Permission-bit management (`chmod` semantics).** Simulated modes add no value; do not fake them.
- **Real kernel / apt / native binaries.** Physically impossible in the sandbox. Succinix is a browser-native Linux (JS runtime + Lifo userland).
- **Inbound external networking.** Ports are virtual previews; tunnels are outbound bridges, not real inbound.
- **Direct external `curl` without CORS.** Use `https://r.jina.ai/<url>`-style proxies.
- **Generic child-process stdin is not available today.** The current Succinix host uses file RPC and headless `Sandbox.commands.run()`, so arbitrary real Node/Python child-process REPLs are unsupported. This is a current transport limitation, not permission to build browser-side substitutes: interactive userland work must use the WebContainer-native Lifo terminal seam above. Do not claim generic child-process PTY support until it is independently implemented and verified.
- **symlinks / hard links.** Not supported by the Lifo VFS.
- **Firefox / Safari / mobile.** WebContainers does not support them; the environment-check error page explains requirements instead.
- **Precise OS-level memory/CPU stats.** Only estimates are available; always mark with `~` and an `(estimated ...)` footnote. Never present estimates as exact.

## Quality Gates (must all pass before finishing)

- `npx tsc -p tsconfig.json --noEmit` → 0 errors
- `node scripts/build-host.mjs` → succeeds
- `npm run build` → succeeds
- `npm run lint` → 0 errors
- `npm run test` → all unit tests pass
- `npm run check:docs` → no broken local references
- `npm run check:plugin-boundaries` → core dirs have no `cordis` imports and
  every `src/plugin/` file carries an invariant marker
- `npm run check:engine-package` → builds the package, writes
  `packages/engine/assets/sha256.json`, validates exports, and runs
  `npm pack --dry-run`
- `npm run test:e2e` → full browser pipeline including the external
  `examples/cordis-app` contract (run escalated when browser access is needed)
- Dev server starts at `localhost:7892` with COOP/COEP headers
- Static self-check: `grep -n '✅\|❌\|🎉\|GREEN' src/ index.html` → no matches