GSV Engineering Contract

GSV is an open-source, user-owned personal intelligence operating environment. Its gateway is a lightweight, globally reachable control plane; agents are durable processes; capabilities gate syscalls; targets are Unix-shaped capability environments backed by GSV, machines, browsers, or services; and adapters own messaging transport.

Ship is the product name. GSV remains the runtime, protocol, package and resource identity; .gsv paths and the gsv target remain stable. Open-network lexicons are the deliberate exception: Ship's public record types use the flat space.ship.* namespace. The external CLI command remains gsv. Operators own public domains, accepted legacy aliases, presentation links and update catalogs. Accounts may lazily materialize a preferred-domain alias only from a recorded canonical hostname; aliases never change the installation ID or the Ship's DID. Kernel-owned reconciliation turns operator release briefs into deduplicated ordinary responsibilities during personal-agent access, without a fleet-wide write or an announcement-only wake.

This document is the root engineering contract for the repository. It explains how to change GSV without eroding that model. Use the code as the source of truth, and update this file when the architecture deliberately changes.

Architecture principles

Preserve user ownership and control

• The user owns the deployment, state, credentials, agents, and connected machines.
• Permissions, approvals, process state, and external provider use must remain inspectable.
• Long-running work must not lock the user out. New input, cancellation, reset, and teardown must remain available while tools or subprocesses are active.
• Late output from cancelled or superseded work must not mutate the active run.

Keep the gateway a control plane

• The gateway owns identity, authorization, configuration, routing, process lifecycle, adapters, and inference coordination.
• Heavy or platform-native computation belongs on the appropriate device, provider, or specialized service.
• Do not move adapter quirks, UI rendering, or device-specific behavior into the Kernel.

Treat installation identity as the outer security boundary

• HTTP requests resolve an accepted hostname through the trusted installation directory before addressing a Kernel. A random wildcard hostname must not allocate Durable Object state.
• The Kernel Durable Object name is the immutable installationId; handles and canonical origins are routing metadata, not security identities.
• Public callers never choose an installationId. Gateways derive it from host routing, adapters derive it from durable links, and background work retains it in owned state.
• A platform-owned shared adapter may bind an external identity through a signed-in human or an authorized process redeeming a code for its human owner. The Kernel derives that owner from the process registry, never a caller-selected uid. Its public webhook and pairing code never choose an installation or local uid; the adapter owns one generation-fenced peer route and rechecks that generation before delayed ingress or delivery.
• Accounts owns space lifecycle state. Only active installations admit ordinary work; restricted installations retain their identity and data while HTTP, WebSocket, adapter, inference, Process-tick, and scheduler admissions fail closed. Work already admitted may reach its terminal boundary, and paused durable work rechecks for reactivation.
• Accounts owns global owner credentials and My spaces sessions separately from Kernel accounts and operator administration. Native email and external identity credentials never merge by matching email. Ownership linking requires current Kernel root authorization plus fresh owner verification; root recovery requires a fresh verification bound to the current owner and exact recovery attempt. An ordinary owner session cannot authorize a root reset. Accounts delivers verification mail independently of the space being recovered.
• An operator reset never clears a Kernel in place or reuses its installation ID. Accounts atomically moves the handle to a fresh installation, retains the old identity behind inactive routing, and records its data as pending deletion until every owning service confirms cleanup.
• Process, R2, ripgit, and installation-owned adapter physical addresses must include installation scope. Shared application and peer objects retain adapter-owned identities and generation-fenced space links.
• ctx.id.name is available only on name-preserving Durable Object paths. An idFromString() callback must recover a previously validated identity from owned state or a trusted routing record.
• Every deployment uses the trusted directory and scoped resource addresses. Historical namespaces may remain only for explicit attribution and cleanup; never reuse them for current admission. See docs/how-to/standalone-retirement.md for the preserved standalone baseline.

Treat syscalls and protocol frames as the primitive boundary

• Fix shared semantics at the syscall, protocol, or owning runtime boundary rather than patching individual callers.
• Model browsers, native clients, machines, and adapter services as protocol peers. Principal, callable syscalls, receivable signals, implemented syscalls, transport, and provenance are independent axes; transport or a claimed peer id never grants authority.
• First-party adapter service bindings use one AdapterGatewayEntrypoint. Deployment-owned binding props supply the adapter identity and attenuated syscall grant; the adapter frame cannot choose either. Kernel-owned CHANNEL_<ADAPTER> binding lookup selects the outbound service without a source-level adapter registry.
• User-state signals remain broadcast independently. An exact adapter destination receives one correlated adapter.send request; the Kernel owns durable retry and route cleanup, while the adapter owns provider presentation, idempotency, ambiguity classification, and body consumption.
• A linked adapter actor may invoke an ordinary syscall only through a Kernel-derived, interaction-scoped human peer whose grant is intersected with the linked account's capabilities.
• Shell, agent tools, CodeMode, apps, and SDK clients may present results differently, but they must share the same underlying primitive behavior.
• Structured frames carry metadata. Potentially large or binary payloads travel through frame bodies and streams.
• space.ship.* methods and records are the lexicons in lexicons/space/ship/. Change a lexicon and run npm run protocol:generate; never hand-write a space.ship schema or NSID.
• Live syscall ledger rows require both the ledger signal grant and sys.ledger.list, scoped to the owning human or root. Clients merge pushed rows and completion updates by sequence; ordinary ledger changes must not trigger another ledger read.
• Whoever accepts a body, request, media object, or background operation owns its completion, cancellation, and cleanup.
• The instance service owns cloud browser save ordering, profile leases, encrypted snapshots and forgetting. Browser profile syscalls expose metadata and deletion under the same owner and browser capabilities. Ordinary stop requires a successful final save, while explicit force, expiry and deletion remain available.
• Cloud computers use the ordinary machine protocol over a private instance-owned connection. One immutable lease owns one boot; loss never replays or recreates a machine's work. Stop, expiry and deletion destroy the computer before releasing its reservation. Browser and computer allowances remain separate.

Treat targets as Unix-shaped capability environments

• A target is an addressable environment that exposes a coherent subset of GSV's filesystem, shell, network, and related primitives. It is not synonymous with a physical machine.
• gsv, a laptop daemon, a browser profile, or an external service account may back a target. A machine is one hardware-backed target provider, not the definition of target-ness.
• Peers and targets are independent projections. A protocol peer supplies principal, grant, transport, provenance, and live implementations; it may offer no target, one target, or multiple targets.
• A targetable syscall must retain the same contract on every target. Do not call an arbitrary provider RPC shell.exec or invent file semantics solely to make a service appear Unix-like.
• Unix-shaped means familiar paths, commands, streams, cancellation, and composition where those concepts are real. It does not promise POSIX compatibility or require every target to implement every primitive.
• An adapter owns messaging transport. An adapter account may additionally provide a target when it exposes a coherent capability environment; that target projection does not move provider identity, credentials, formatting, retry, or delivery policy into the Kernel.

Keep the agent interface small and composable

The fixed model-facing surface is Read, Write, Edit, Delete, Search, Shell, CodeMode, and Send. Send is the run control, message and yield, as a tool, and is the only tool that is not a capability. Add capabilities beneath that surface through syscalls, targets, or CodeMode instead of growing a bespoke tool for every integration.

Search exposes the provider-neutral, targetable web.search syscall. It defaults to gsv, whose implementation uses an optional operator-owned service binding; other accessible targets may advertise the same syscall. Filesystem search uses Shell commands or CodeMode fs.search. Provider credentials and metering belong to the provider implementation.

GSV is Linux-inspired because familiar, orthogonal semantics reduce instruction burden for models and humans. This is a design model, not a promise of POSIX compatibility.

Treat agents as real processes

Each space has one personal human account, plus explicit root administration and non-login agent accounts. Setup derives the ordinary account name from the space handle; existing account identities and homes remain stable. Normal sign-in selects the personal account without asking for a username. Root remains explicit. People owns the space's public profile at /profile and cross-space contacts; contact invitations do not create local human accounts.

Processes have identities, histories, permissions, queues, pending work, and lifecycles. Subagents and subprocesses are not special chat records. Preserve process invariants across normal completion, interruption, restart, and teardown.

The personal agent account is the user's personal intelligence. Its canonical user-facing conversation is Ship. One Kernel-marked interactive process handles Ship across user interfaces; its pid is replaceable and otherwise follows ordinary process lifecycle. Other processes are visible work, even when they run as the same account. Kernel SQLite owns one durable responsibility ledger (r12y) for promises, delegated work, follow-ups, maintenance, and recovery that must survive a run. The Ship sees the owner ledger; a delegated child sees only its assignments and their ancestor records. A delegated process is an ordinary process acting in a worker role, not a second orchestration runtime.

Ship's default delegation uses an ordinary owned Crew account through proc delegate --as. Account homes separate conversation and execution instructions; the human owner's context and memory remain shared. Account identity selects prompt context, and children follow ordinary spawn rules.

Newly archived Ship slices may enqueue ordinary memory-review responsibilities. Process retains sources until the Kernel durably accepts them and transfers any remainder before teardown. Kernel owns their ordered queue independently of the replaceable pid, deduplicating and serializing admissions per owner under the configurable memory.review source. Ship delegates bounded review through the existing Crew and responsibility workflow. Review instructions merge evidence into current standing memory and the personal wiki; compaction never waits for that work, and worker compactions do not recursively create reviews.

A Process context epoch freezes the exact rendered system prompt, its source manifest, and the initial responsibility baseline across normal runs. Later responsibility revisions enter as ordered GSV events rather than rewriting the prompt. Kernel-owned availability facts such as accessible targets, ready MCP servers, the current date, timezone and owner language preference, the skill catalog, the Ship's handle and address, and the managed mailbox address follow the same rule: Process stores an initial and last-observed projection and atomically appends meaningful deltas before generation. Reset, compaction, Process replacement, or effective standing-context changes close and archive the epoch, including its exact prompt, Process activity, projection and responsibility transitions, and run boundaries.

A Process may submit its own handover through proc.history.compact. The Kernel supplies its owning tool identity; Process stages it in the active run and installs it after tool results settle, before another generation. Compaction may archive completed steps within a run while retaining its original input and unseen results. Installation archives first and commits atomically; cancellation or replacement cannot install a stale handover. Emergency summarization covers all model-visible records in bounded passes. Shared standing memory remains in the human's context.d, detailed knowledge in the personal wiki, and unfinished commitments in r12y.

Process history stores typed message, note, call, result, and event records. Runtime events retain registered payloads, severity, and audience; admission preserves queue provenance. An assistant turn can own several records under one compatibility message identity. During the typed-history transition, the existing prose and provider projection remain available alongside those records; archives, forks, and media cleanup preserve the entire group.

Canonical user-facing conversations are not Process histories. Conversations retain only committed user-visible Messages across Process replacement or deletion; Process history retains reasoning, drafts, tools, results, and run-control choices for inspection. message send commits a user-visible Message without finishing the active run, so a Process may update the user while continuing work. Every human-facing run must eventually call yield; a final send composes as message send ... && yield, while a bare yield completes silently. These Process-owned commands do not add model tools or require shell approval. A bounded IPC call instead returns ordinary assistant output as its durable Process result, independently of human delivery. Clients may opt into raw Process observation, while adapters receive only exact routed adapter.send requests.

Process history uses typed message, note, call, result, and event records. Storage owns legacy inference; model context, compaction, and client presentation each render those records at their owning boundary. Preserve the captured provider-context contract when changing rendering. Person-only events remain inspectable without entering provider context or summary input. Format-2 history synchronization replaces complete message groups, including late companions and media changes; reset and compaction invalidate earlier cursors. See docs/architecture/process-history.md.

Contact conversations have no mandatory Process handler. Pairing and first-message acceptance create no agent commitment. A human may hand a contact generation to Ship through one ordinary responsibility, or bind replies to existing Ship work when sending for a specific task. Human and Process authorship remain visible but do not choose the local handler. Duplicates and delivery receipts never admit new agent work. People owns social presentation; the Kernel owns contact authority, private inbox state, public profile publication and first-contact admission.

Prefer fewer mechanisms

• Consolidate duplicate paths and delete obsolete ones when behavior remains clear.
• Validate hostile input at external boundaries. Represent internal assumptions as explicit invariants and tests instead of speculative defensive branches.
• Inline trivial one-use helpers. Keep helpers that name a meaningful domain operation or centralize policy, ownership, or lifecycle.
• Split large files by responsibility, owner, or state-machine boundary—not merely by line count.
• Compatibility must correspond to an explicitly supported upgrade path. A hard cutover should remove the old path end to end.
• Optimize for comprehensibility and a smaller state space, not raw line-count reduction at the expense of correctness.
• Measure user-visible latency before optimizing it, and avoid unnecessary serial work on critical paths.

System ownership

• packages/gsv/src/services/: public Worker RPC contracts for Accounts, inference execution, lifecycle, optional commercial services, mail, and adapters. Operators compose public implementations with their own optional services.
• workers/gateway/src/kernel/: authentication, capabilities, syscall dispatch, configuration, process registry, routing, schedules, adapters, and user connections.
• workers/installations/: required public Accounts directory, ownership, onboarding, operator administration, recovery authorization, reset preparation and durable deletion coordination. Commercial policy and usage remain owned by the optional operator service.
• workers/gateway/src/process/: agent loop, history, queued input, pending tools, approvals, cancellation, context assembly, and process-scoped media.
• workers/gateway/src/drivers/native/: the in-process gsv target provider, including its filesystem, shell, and network-backed command environment.
• workers/gateway/src/conversation/: canonical user-visible message history, immutable resource references, hot SQLite retention, and immutable R2 archive segments.
• workers/gateway/src/syscalls/ and workers/gateway/src/protocol/: public runtime contracts and frame transport.
• workers/gateway/src/inference/: inference coordination and the authorized callback into machine model transport. Gateway owns credentials, request admission, cancellation and stale-result fences; it does not execute provider SDKs or use an AI binding directly.
• workers/inference/ and packages/inference/: required inference execution Worker, durable request execution, shared provider integration, model transport, media processing and the public reference provider policy. An operator can deploy this independently of Gateway; commercial implementations consume the same execution runtime.
• packages/gsv/: public client and protocol types.
• packages/browser/: shared browser commands, semantic page references, shell, and filesystem driver. Backends supply CDP, tab operations, and persistence; browser state belongs to the backend instance.
• web/: Instrument web UI, setup/login, shared browser-side gateway services, and the development design catalog.
• host/apps/desktop/: desktop host for the shared Instrument UI, native input, local control, machine enrollment through the CLI, and window lifecycle.
• host/apps/cli/: user, deployment, administration, and OS service-control commands.
• host/apps/machine/: the gsvd machine driver, concrete tools, transfer ownership, reconnect, logging, and shutdown.
• host/helpers/: separately supervised local transcription and speech playback processes.
• host/crates/: shared gateway transport, host configuration, Desktop IPC, and Windows SCM/process ownership primitives. host/ owns their Cargo workspace and build artifacts.
• workers/adapters/: platform-specific messaging workers and identity normalization.
• extension/: browser-backed target and browser integration.
• workers/instances/: optional cloud browser and computer provisioning, profiles, human control, metering, and instance-owned cleanup.
• workers/ripgit/: git-backed repositories and filesystem storage operations.
• workers/pds/: optional ATProto host for each installation's public repository, its did:plc, files and firehose. The Kernel decides what is published; the PDS signs, stores and serves it.

Keep platform-specific identity and delivery behavior in its adapter. Keep visual presentation in the web and Desktop clients. Keep target selection below stable syscall contracts.

Windows uses an automatic SCM service for gsvd, with a dedicated execution account, protected executable, and daemon-only enrollment in ProgramData. CLI and Desktop remain user processes. The service control pipe authorizes its enrolling owner explicitly; Desktop and input helper IPC remain same-user. OS service privilege must never become an agent shell privilege by accident.

Runtime invariants

Processes and cancellation

• Provider history must remain structurally valid.
• Queued messages must not be lost accidentally.
• Pending tool calls and tool results must stay consistent.
• A stale run must not mutate active state.
• Cancellation must propagate to the component that owns the active operation.
• Browser handoff links are Kernel-owned records, independent of editable work details. Cancelling work commits locally; durable reconciliation retries provider cleanup and resumes work whose handoff ended.
• Request cancellation does not recursively kill an already-created durable shell session unless that contract explicitly says so.
• shell.cancel explicitly stops a durable device session and its process tree. The device owns termination independently of the caller connection; polling remains available for the terminal result. Device disconnects leave session identity available for a status check after reconnect.
• Recoverable shell starts use shell.exec with start: true and a caller-persisted fresh sessionId. The Kernel persists its target before dispatch and the machine claims that exact identity before spawning. Recovery only polls or cancels; it must never replay a start or uncertain stdin.
• proc.abort stops the active run, proc.reset resets history while preserving the process, and proc.kill tears the process down.
• A successfully killed pid remains terminal across Durable Object eviction and must never be reused for a replacement process.
• Archive and media cleanup must remain coherent across reset and kill.

Protocol and routing

• Payload types are explicit at syscall and protocol boundaries.
• Body streams have one owner and one terminal outcome: consumed, forwarded, or cancelled.
• Device disconnects, timeouts, malformed responses, and caller cancellation must clean up routes and bodies.
• Filesystem, shell, and network behavior must remain consistent between local gateway and device implementations.
• Adapters receive stable actor and surface semantics; channel-specific identifiers do not leak into generic RPCs.
• Private user surfaces default to the personal process. Direct access to another process is an explicit, visibly labeled work session; opening one surface must not silently redefine the user's personal intelligence elsewhere.
• A run route directs immediate message streaming and delivery to one endpoint; it does not own the canonical conversation. Personal Ship follows the owner's latest human message origin across runs, falling back to the last authorized private messenger when the selected client disconnects or is inactive for five minutes. Client activity only refreshes the selected client's idle timer; it never selects a destination or revives an expired selection. Opening a client or keepalives do not claim activity. Explicit Work, group and contact routes stay fixed. Each committed message retains its chosen route through retries; other clients synchronize it without another notification.

Data and security

• Enforce authorization in the Kernel, not only in UI or callers.
• Only what a person chose to make public goes to the open network. The Kernel owns who may publish, approval of agent publishing and the collections features reserve.
• Agent approval follows the actual destination through native commands and CodeMode. The Kernel retains the owning tool and the Process applies its run policy before nested machine, mail, or MCP effects; a cancelled or superseded owner cannot authorize dispatch. Future shell schedules require their own approval by default.
• Managed onboarding capabilities authorize only first-boot setup for one installation. Store them hashed in accounts, keep them out of URLs after the browser reads the fragment, and let only the Kernel create local credentials.
• Accounts owns open registration for verified owners. Each self-service signup resumes one durable provisioning operation; private policy prepares its plan before setup authorization. Contact invitations remain Kernel-owned and do not grant or reserve signup places. Desktop owner sessions use explicit bearer authentication and never grant Kernel login or root recovery.
• A signed-in human or a permitted process acting for its human owner issues device enrollment invitations scoped to the installation, owner account and exact target. Invitations expire, are single-use, and store only hashed authorization. Receivers persist their credential before redemption; the Kernel commits its hash and the redemption receipt atomically. Closing or cancelling an invitation never revokes an already-paired device.
• Never hardcode or log secrets, raw authentication material, QR payloads, prompts, tool arguments, or private file contents.
• Persist file and media references in history, retain durable content once as immutable media under the run-as agent home, and scope temporary keys to the owning process. Hydrate bytes only while building model context or resolving an explicit resource read.
• Canonical Messages store immutable resource references rather than duplicating bytes. A Process must retain an exact source revision before committing a reference whose source lifetime is not already durable.
• Telemetry uses an explicit allowlist and records timings and outcomes rather than user content.
• Unexpected failures must remain diagnosable at the owning boundary. Preserve the cause for authorized inspection and emit a closed failure record, including failures before admission. Never replace an exception with a generic message or empty result without retaining a diagnostic reference. Export only the bounded, redacted exception fields in the shared diagnostic schema; keep full error objects, request/response bodies and private content out of telemetry.

Schema migrations

Durable Object SQLite and managed D1 schemas use versioned migrations in:

• workers/gateway/src/kernel/schema/
• workers/gateway/src/process/schema/
• workers/gateway/src/schema/runner.ts
• workers/ripgit/src/schema.rs

Do not create tables, indexes, or ad hoc ensureColumn migrations from store constructors. Do not edit a migration that has shipped; add the next numbered migration. Collapse to a new baseline only for an explicit release/reset policy, and preserve supported upgrade paths with migration tests.

Use Durable Object storage KV for a single opaque record that is read and written as a unit. Introduce SQL tables and migrations when the data needs relational queries, indexes, constraints, or multi-row operations.

Change discipline

• Do not rewrite or delete maintainer-authored comments unless the maintainer explicitly requests it. If a change makes one stale, preserve it and call it out for direction.
• Write active docs and instructions in terms of current concepts. Keep change history in release notes or migration guides, and explain legacy behavior where supported compatibility requires it.

Protected prompt and context content

• Keep production prompt text and repository-defined defaults or seeds for system config/ai/context.d/* and user or agent account ~/context.d/* in workers/gateway/src/prompts/**.
• Write active standing defaults and standalone task prompts as Markdown files imported by TypeScript. Use npm run review:prompts to edit and preview them; keep runtime selection and structured event formatting in code.
• Each standing source in prompts/{system,ship,crew,user}/context.d/ is one complete entry. Its path defines scope and filename; keep shared instructions, including memory guidance, in system context.
• Treat workers/gateway/src/prompts/** as read-only unless the user explicitly requests a prompt or standing-context content change.
• Do not edit prompt or seeded context.d content to work around runtime, protocol, tool-discovery, or UI behavior. Fix the owning implementation boundary.
• If a task appears to require changing protected prompt or context content without explicit authorization, stop and ask first.

1. Inspect the current branch, diff, callers, and owning subsystem before editing.
2. State the invariant and the component that should own the behavior.
3. For broad cleanup, present the proposed batch before changing behavior so maintainers can supply historical context.
4. Fix the central boundary, remove superseded paths, and avoid caller-specific workarounds.
5. Validate the smallest relevant surface. Cross-boundary changes require tests on both sides.
6. Run a clean-instance end-to-end flow for onboarding, deployment, protocol, authentication, or lifecycle changes.
7. Commit completed batches separately with short, imperative, lowercase subjects.

Preserve unrelated user changes in a dirty worktree. Do not broaden a cleanup batch merely because nearby code could also be changed.

Repository map

gsv/
├── workers/
│   ├── gateway/   # Kernel, Process, syscalls, inference, filesystem
│   ├── adapters/  # External-platform Worker implementations and test channel
│   ├── pds/       # ATProto host for public repositories
│   └── ripgit/    # Git-backed repository Worker
├── packages/gsv/  # Public TypeScript client and protocol
├── web/           # Instrument web UI and browser-side gateway integration
├── host/
│   ├── apps/      # Rust CLI, Desktop, and machine applications
│   ├── helpers/   # Isolated transcription process
│   └── crates/    # Shared host transport, configuration, and IPC contracts
├── extension/     # Browser target
├── engineering/   # Detailed implementation and product guidance
├── docs/          # Architecture and user/reference documentation
└── scripts/       # Development and release automation

Development and validation

Install dependencies:

./scripts/setup-deps.sh

Build the web assets before starting the local multi-worker stack; the gateway serves web/dist:

npm run build --workspace web
npm run dev

Validate only the surfaces affected by the change:

Before Desktop Rust checks, build its shared frontend with npm run gsv:build && npm run build:desktop --workspace web.

• Managed service implementations: validate them in their owning deployment repository against packages/gsv/src/services/
• Gateway: cd workers/gateway && npx tsc --noEmit && npm run test:run
• Web: cd web && npm run check && npm run test:run && npm run build
• Desktop and transcription helper: cd host && cargo fmt --package desktop --package transcriber --check && cargo test --package desktop --package transcriber && cargo clippy --package desktop --package transcriber --all-targets -- -D warnings
• Public SDK: npm run gsv:check && npm test --workspace packages/gsv
• CLI: cd host && cargo fmt --package gsv --check && cargo test --package gsv
• Machine: cd host && cargo fmt --package machine --check && cargo test --package machine
• ripgit: cd workers/ripgit && npm test
• Browser extension: cd extension && npm run check && npm run test:run && npm run build
• Cloud instances: npm run typecheck --workspace workers/instances && npm test --workspace workers/instances; after starting the local stack, npm run smoke:browser
• Shared browser core: npm run browser:build, then the browser extension checks above and checks for each provider that consumes it.
• Discord, Telegram, Slack, or test adapter: cd workers/adapters/<name> && npm run typecheck

Protocol or client changes may affect gateway, web, CLI, devices, and adapters even when only one type definition changed. Validate each actual consumer.

Documentation is an output of the change, not a follow-up. A change to product-facing behaviour updates docs/ in the same pull request, and the GSV Manual (deathbyknowledge/gsv-manual, which every installation imports for its agents) in its own pull request when the operating model or a user workflow moved.

• Docs: npm run docs:check

That check verifies the site's links, redirects and sidebar, refuses content that is not publishable, and fails a pull request that touches a documented surface without changing one of the pages that own it. tools/docs/coverage-map.json maps source paths to those pages; when a new page takes over a surface, add it there. When a change genuinely needs no documentation, say so: add the docs-not-needed label, or put a line in the pull request body starting with Docs: that gives the reason. Manual-only work is recorded the same way, as Docs: gsv-manual PR <url>.

Deployment model

• Operator stack: build and inspect npm run deployment:plan, then apply npm run deployment:deploy with the existing operator configuration and Alchemy state.
• Web code: build web, then deploy the Gateway that serves those assets through the same operator composition.
• Adapter code: update the affected adapter Worker through the operator composition, preserving its resource identities and application credentials.
• ripgit code: deploy that worker separately.
• CLI or extension code: build and publish through their release path; a gateway deploy does not update them.

Deployment and CLI command reference lives in docs/reference/cli-commands.md.

Code and commit style

TypeScript uses two-space indentation, double quotes, semicolons, import type for type-only imports, and explicit boundary types. Avoid any outside tightly constrained interop.

Rust uses cargo fmt, non-blocking async code, Result with ?, and contextual errors at I/O and network boundaries.

Commit subjects are short, imperative, lowercase, and scoped to one logical change, for example:

• simplify process cancellation
• unify device response cleanup
• add disposable e2e smoke

Detailed guidance

• Architecture: docs/architecture/
• Rust CLI, daemon, Desktop, and local IPC: docs/architecture/rust-host-applications.md
• Syscalls and protocol: docs/reference/syscalls.md and docs/reference/websocket-protocol.md
• Public documentation and its currency rule: docs/ and tools/docs/coverage-map.json
• Web product and app design: engineering/builtin-app-design.md

Read the relevant detailed guide before changing that subsystem; do not duplicate its full policy here.