Operating Neon Law Navigator

Deploy your own

Follow this workshop to stand up your own Neon Law Navigator. navigator ops gcp setup stands the same Rust stack our attorneys run up on your Google Cloud project. Free, open, and yours to keep.

Agenda

Six steps, each tagged with its Bloom verb. You are the admin operator; the navigator CLI is the instrument:

• Create — stand up a billed project and authenticate.
• Predict — run --dry-run and read every API call before sending one.
• Identify — name the twenty-three Google Cloud APIs the provisioner enables.
• Explain — describe the VPC, six core buckets, optional archive/telemetry lanes, private image registry, and configured service deployments.
• Execute — bring up the cluster, the static IP, and Fleet membership.
• Verify — ship the service images and confirm /readyz answers 200.

Bring your own project

navigator ops gcp setup provisions into a project; it does not create one. Start by creating a project and attaching a billing account, then authenticate so the CLI can act as you:

gcloud projects create your-project-id --name "Neon Law Navigator"
gcloud billing projects link your-project-id --billing-account "$BILLING_ACCOUNT_ID"
gcloud auth login --force --update-adc
gcloud auth print-access-token >/dev/null
gcloud auth application-default print-access-token >/dev/null

Before provisioning, confirm billing is enabled for every selected project. Load each row from the operator-managed root; check a separate registry project too when your installation uses one:

for CONFIG in "$NAVIGATOR_DEPLOYMENTS_DIR"/deployments/*/config.toml; do
  set -a; eval "$(grep ' = "' "$CONFIG" | sed 's/ = /=/')"; set +a
  gcloud billing projects describe "$NAVIGATOR_GCP_PROJECT_ID" \
    --format='value(projectId,billingEnabled)'
done

Each selected runtime project must show True. If a row is False, attach billing before running setup. Check a registry project by supplying its operator-managed ID:

gcloud billing projects describe "$NAVIGATOR_IMAGE_REGISTRY_PROJECT" \
  --format='value(projectId,billingEnabled)'

Dry-run first

Before you change anything, read the plan. The --dry-run flag records every REST call and gcloud shell-out and prints them without sending traffic:

cargo run -p cli -- ops gcp setup --project-id your-project-id --dry-run

Private assets and domain restricted sharing

Every deployment bucket remains private. navigator ops gcp setup grants the deployment Google service account roles/storage.objectAdmin on its assets, documents, exports, logs, and applications buckets, then maps both Kubernetes service accounts (navigator-web and workflows-service) to that Google identity through Workload Identity. The PostgreSQL backups bucket is the exception: only the navigator-postgres-backup Kubernetes service account gets object admin on it, and the web identity gets nothing. It never adds allUsers and never changes constraints/iam.allowedPolicyMemberDomains. The applications bucket is still provisioned, but nothing reads it: the Portal is retired, and /app/projects/{code}/portal redirects to the matter show page.

The public website receives only marketing bytes through GET /assets/*. web reads that object from NAVIGATOR_ASSETS_BUCKET with the deployment identity and returns it with its stored content type, X-Content-Type-Options: nosniff, and a one-hour public cache. Unsafe keys and missing objects return 404; storage failures return 502. There is no parallel anonymous route for documents, exports, or logs. This is an application delivery boundary, not a Navigator persons.role or Project-participation grant.

Set NAVIGATOR_ASSET_BASE_URL=$NAV_BASE_URL/assets in each deployment's config.toml — it is a plaintext coordinate the ops ship preflight requires. Setup also gives the active gcloud identity the same bucket-scoped object CRUD role so the operator and the Kubernetes runtime can inspect and repair objects without a public or project-wide grant.

Publish the public asset inventory before ops ship. A full or image-only roll reads NAVIGATOR_ASSETS_BUCKET and stops before any rollout when a required object is missing or the bucket cannot be read. The preflight and the post-roll check use one inventory. On a source checkout that inventory is every markdown image under server/content, every responsive gallery variant, the brand media keys, and every licensed webfont face. On a deploy-only checkout (--deployments-dir with no server/content directory) blog references are absent, and the inventory is the workshop images embedded in the CLI plus those same gallery variants, brand media keys, and fonts. Restart-only skips both checks.

navigator ops assets build --src /path/to/source-jpegs
navigator ops assets upload
navigator ops assets fonts upload --family eb-garamond --dir /path/to/woff2
navigator site asset upload --host "$NAVIGATOR_PUBLIC_HOST" "$ASSET_PATH"

assets build then assets upload publishes the gallery variants. assets fonts upload publishes one licensed family. site asset upload publishes one finished image, including brand media and a workshop slide. Run the publish that covers the inventory, then ops ship.

After setup, verify both identities and reject an anonymous principal:

runtime_gsa="$NAVIGATOR_GCP_SERVICE_ACCOUNT_ID@$NAVIGATOR_GCP_PROJECT_ID.iam.gserviceaccount.com"
operator_account="$(gcloud config get-value account)"
case "$operator_account" in
  *.gserviceaccount.com) operator_member="serviceAccount:$operator_account" ;;
  *) operator_member="user:$operator_account" ;;
esac

for bucket_name in \
  "$NAVIGATOR_ASSETS_BUCKET" \
  "$NAVIGATOR_DOCUMENTS_BUCKET" \
  "$NAVIGATOR_EXPORTS_BUCKET" \
  "$NAVIGATOR_LOGS_BUCKET"
do
  iam_rows="$(
    gcloud storage buckets get-iam-policy "gs://$bucket_name" \
      --flatten='bindings[].members[]' \
      --format='value(bindings.role,bindings.members)'
  )"
  printf '%s\n' "$iam_rows" |
    awk -v runtime="serviceAccount:$runtime_gsa" -v operator="$operator_member" '
      $1 == "roles/storage.objectAdmin" && $2 == runtime { runtime_ok = 1 }
      $1 == "roles/storage.objectAdmin" && $2 == operator { operator_ok = 1 }
      $2 == "allUsers" { public = 1 }
      END { if (!runtime_ok || !operator_ok || public) exit 1 }
    '
done

The Navigator deployment matrix

Each deployment has one config.toml and one encrypted secrets.enc.yaml under the operator-managed deployment root: $NAVIGATOR_DEPLOYMENTS_DIR/deployments/<row>/. The config supplies that row's project, region, cluster, namespace, host, and image settings. Keep each row's database, buckets, Kubernetes namespace, runtime identity, and Secret isolated from other rows. The private root is supplied by the operator and is not part of this source repository.

The /app mount and HTTP route ownership

/app is the container filesystem mount, not a public URL prefix. The images install their executable and common runtime material there:

Each executable supplies only its public brand routes to portal::bootstrap. The mounted application crate always owns these HTTP paths and every descendant:

• operational and public ingress: /version, /assets/*, /webhook/*, /docusign/*, /public/*, and /dioxus-demo;
• application and control surfaces: /app/*, /app/api/*, /app/health, /app/readyz, /app/mcp/*, /auth/*, and /docs/*;
• API documentation: /app/api and /app/api/openapi.json.

The brand-owned public routes are:

• Neon Law: /, /contact, /team, /team/nick, /blog, /blog/{slug}, /notations, /workshops/*, /presentations/*, /privacy, /terms, /robots.txt, /sitemap.xml, and /llms.txt.

This precedence is fail-closed, not merge order. Each brand declares every route it mounts; startup returns an error if an exact path or descendant overlaps a Navigator-owned prefix. A brand therefore cannot shadow data access, authorization, control, API, health, or protocol routes.

neon — the whole brand seam

A brand crate is exactly one value: the portal::hosting::Brand each compiles — its key, its telemetry service name, and the bounded public routes listed on the previous slide. Everything else is the shared application they mount, and the portal renders under the mounting brand's chrome, so branding the binary brands the portal too: one brand seam carries the public site, the signed-in portal, and the telemetry identity together.

That thinness is the customization story. A custom Navigator changes minimal surface area: write your own brand crate in the neon shape — a Brand value and a call to the shared run loop, nothing more — build it into your own <brand>-server image, and interact with the remaining published images (navigator-workflows-service, the trigger images) unchanged. The two brand Containerfiles are deliberately identical modulo the brand name, so the image recipe for a new brand is the existing one with your crate's name.

Network and storage buckets

With the APIs on, the CLI provisions the data plane and runtime identity:

• A custom-mode VPC with one explicitly named regional subnet and private Google access. The deployment's GKE cluster is pinned to both names.
• Six private Cloud Storage buckets, all uniform bucket-level access: -assets (marketing objects served through the same-origin /assets/* application route), -documents (client documents), -exports (Parquet/Iceberg archives), -logs (the Nearline log-sink destination), -postgres-backups (the PostgreSQL WAL archive and base backups, expired at 30 days), and -applications (still provisioned; the retired Portal's bundles are no longer read or written). A deployment may also name separate archive and telemetry buckets for long-term snapshots and telemetry landing data.
• A deployment-specific Google service account with the Secret Manager accessor role, object access on only that deployment's core buckets other than PostgreSQL backups and any named archive/telemetry lanes, Workload Identity bindings for the namespace's navigator-web and workflows-service Kubernetes service accounts, and permission to sign its own GCS URLs.
• A separate Workspace Drive service account with no runtime GCP roles. An operator creates one JSON key, records it in that deployment's secrets.enc.yaml, and grants its OAuth client domain-wide delegation in the selected Workspace.

How a matter's pages reach a client

Each Project has its own source repository — for example, example-organization/sample-project — holding navigator.yaml, Markdown Drafts, and YAML. A matter's client-facing pages are its Matter Pages, declared under pages: in navigator.yaml and rendered by web on the matter show page, /app/projects/{code}, after the session and Project participation row are checked. No bundle is built, published, or streamed. /app/projects/{code}/portal and every path beneath it answer 301 to the matter show page.

flowchart LR
  subgraph repo["Project repo — example-organization/sample-project"]
    src["navigator.yaml pages: + drafts/"]
  end
  subgraph nav["Navigator — neon-server"]
    web["web renders the matter show page<br/>/app/projects/acme"]
  end
  client(["Client browser"])

  src -- "staged source" --> web
  client -- "GET /app/projects/acme" --> web
  web -- "check session + participation" --> web

A document's bytes and authorization are separate

Inside the documents bucket, the storage key is content-addressed: store::documents::ingest_bytes writes bytes at blobs/<sha256>. The Surreal asset row is the Project-scoped record: it carries the Project association, provenance, visibility, and the reference to that object. The portal checks that row before streaming a document, so clients never receive bucket credentials or direct object URLs.

The ingest deduplication decision is scoped to the Project, even though the key shape is not: an existing matching asset on the same Project avoids a second write, while a matching asset on another Project does not authorize reuse of its row. Because two rows can name the same content-addressed key, a governed expunge checks whether another asset row still references the object before deleting its bytes. That reference check keeps a deletion in one Project from removing bytes still needed by another.

This is why Project growth does not require a documents bucket per Project. The bucket is a private deployment lane; the Surreal record supplies the Project boundary, and the application supplies the authorization boundary.

What setup owns — and what follows it

ops gcp setup provisions the hostable cloud substrate: APIs, VPC and subnet, Cloud Router/NAT, private buckets, identities, registry access, GKE, Gateway IP, workload identity, Fleet integration, and KMS. It deliberately stops at the cloud/cluster boundary. Finish the deployment through these adjacent owners:

Separate people, Git transport, and machine access

Forgejo's reserved bootstrap administrator holds the first administrator seat; its random password is discarded and password sign-in is disabled. Operators use Forgejo's administrator CLI rather than sharing that password.

Require the gate and protected-main policy

Read the actual gate's check context from a run on the installation. Review policy drift without writing:

navigator ops forgejo setup example-firm/sample-litigation \
  --url https://forge.example.test/ --check-context ci --dry-run

Use the observed context in place of ci. The reconciler prepares required checks, signed commits, PR-only changes, administrator enforcement, and squash-only merging. Verify direct pushes, force pushes and branch deletion are denied. The scheduling command requests a governed merge; it does not install an automatic PR scheduler.

CODEOWNERS, trusted check identity, merge-time review-thread enforcement, automatic scheduling, and branch cleanup on closure remain separate migration gates. A successful policy API response does not prove all of them.

Bind the workflow to one Project and one commit

Deployment Actions stays disabled until isolated, ephemeral runners and the Project workflow are proved. Port the existing gate rather than replacing its checks. Every PR update must validate the pinned manifest and run navigator project gate --ci; authorized live reads use the document-check path.

Forgejo Actions OIDC can identify a run to an external service. The migration must verify its issuer, audience, expiry, repository, workflow, event, ref and commit before issuing short-lived Navigator or cloud access. Resolve the authorized Project from the repository binding, then check the manifest agrees. Untrusted YAML cannot select another Project, deployment or artifact prefix.

PR jobs receive no publication credentials. After a governed merge, verify the merged commit and publish only that Project's allowed artifacts. Prove the same flow after credential expiry and on a denied cross-Project request.

Notify failures even when the manifest is broken

The existing GitHub notice runs on a push to main after the manifest parses. The Forgejo migration must also report PR check failures, invalid or missing manifests, publication failures, and recovery to the existing Project channel. Resolve that channel independently from trusted repository metadata. Include the commit, run link and outcome, with durable retry and duplicate suppression. Document content and credentials stay out of notices.

Notification failure must not turn a failed gate into success. Exercise a malformed manifest and a workflow that cannot start, then confirm the operator receives the failure through the trusted reporting path.

Restore the repository before cutting over

PostgreSQL physical backups cover its databases. They do not contain Forgejo's separate Git, LFS and attachment files. A complete recovery also needs consistent database and file snapshots, encrypted recovery configuration, and a tested restore procedure. Retained volumes alone are not backups.

For Git history, prepare a stable local mirror and verify a portable bundle:

git clone --mirror https://forge.example.test/example-firm/sample-litigation.git /path/to/mirror.git
navigator ops forgejo bundle /path/to/mirror.git /path/to/repository.bundle

The command restores into a scratch mirror and checks object integrity, ref hashes and the default branch before publishing a new file without overwrite. It covers refs present in that mirror, including explicitly fetched PR refs. It excludes forge metadata, LFS and document objects. It does not schedule or upload archives.

Three operating modes, two deployment profiles

The deployment that says its matters are sample

NAVIGATOR_SIMULATED_MATTERS is the second selector, and it answers a different question from the first. The profile above decides which runtime wiring a boot gets; this decides whether the matters in front of a visitor are invented.

Left unset or empty it follows the profile: a dev boot carries sample matters because that is all a dev boot has, and a production boot does not, because production is where the real files are. Exactly true or false overrides that in both directions, and every other value — TRUE, 1, yes, a case or whitespace variant — is rejected rather than resolved to the permissive answer. That exactness is the point: a typo that quietly read as true would seed invented clients into a database of real ones.

The override that matters is true under a production profile. A hosted demonstration row may use a production runtime profile, so it must explicitly enable simulated matters in its own $NAVIGATOR_DEPLOYMENTS_DIR/deployments/${ROW}/config.toml:

NAVIGATOR_SIMULATED_MATTERS = "true"

Two things follow from that value. store::seed applies the sample-matter fixture, so the row carries sample-litigation, sample-transactional, and sample-estate rather than an empty portfolio. And every page publishes a site-wide banner saying the matters are sample — which is why a staging host is safe to hand to another operator, because a demo matter cannot be mistaken for a real file.

It is a coordinate, not a credential, so it lives in config.toml beside the buckets and hostnames rather than in that deployment's secrets.enc.yaml. Adding it needs no SOPS re-encryption on either row.

Other hosted rows may state "false" explicitly for documentation. The code already reads a missing value as false under a production profile, and ops ship renders false into the web env when a deployment's config omits the key, so the substitution is deliberately optional: a config that never mentions it still renders and still ships. A key that could halt a production rollout by being deleted would be a worse failure than the one it guards against.

Configuration precedence: the first source wins

Local dev controls: inputs read by navigator dev

Local runtime: what .devx/env generates

The store: SurrealDB

Where SurrealDB authorization lives

Deployed runtime: core web and worker wiring

Deployed runtime: identity and access

web-env.yaml uses # NAVIGATOR_OPTIONAL_ENV <KEY> to mark an optional coordinate (OAUTH_APPLE_CLIENT_ID, OAUTH_MICROSOFT_ALLOW_ANY_TENANT); ops ship emits its entry, quoted, only for a nonblank value. | Bootstrap Owner | NAVIGATOR_BOOTSTRAP_OWNER_EMAIL (config.toml) | Missing: ship refused; unset: no JIT identity | | Protected firm Entity | NAVIGATOR_BOOTSTRAP_COMPANY | Shook Law PC is protected either way | | Google token policy | GOOGLE_OAUTH_CLIENT_IDS, GOOGLE_OAUTH_REQUIRED_HD | No client/domain pin | | Google token endpoint | GOOGLE_TOKENINFO_URL | Google default | | Password door | NAVIGATOR_IDENTITY_PLATFORM_API_KEY | OIDC-only login | | Password endpoint | NAVIGATOR_IDENTITY_PLATFORM_ENDPOINT | Google default | | Identity Platform admin calls | NAVIGATOR_GCP_METADATA_ENDPOINT | GCE metadata server default |

Deployed runtime: email, signatures, and billing

Deployed runtime: repositories, content, AI, and scheduled work

Provision and ship: variables read by the operator CLI

Ancillary operations and opt-in test controls

The DNSimple CLI transaction uses operator-shell variables DNS_SIMPLE (or legacy DNSIMPLE_API_TOKEN), DNSIMPLE_TOKEN, DNS_ACCT, and DNS_ZONE. None belongs in a deployment config.

When sample data appears

Secrets: the invariants that gate the boot

web fails loudly rather than degrading silently: a missing required value crashes startup with a structured enforce_deployment_invariants error naming exactly what is absent. So a CrashLoopBackOff is almost always a missing secret:

kubectl logs deploy/navigator-web -n navigator

Role rings: who can do what

The rings display the five stored roles in their authority order: owner > admin > lawyer > clerk > client. Owner inherits Admin and Lawyer capability; Admin inherits Lawyer capability but cannot govern Owner. Clerk is deliberately not a weakened Lawyer account. Anonymous is outside every ring and sees public pages only. Clients use the portal for their own matters. Clerks reach /app/projects like everyone else and get a read-only rendering of their firm-assigned Projects and the disclosed lawyer DRI; they never give legal advice. Owner, Admin, and Lawyer are lawyers, and MCP, Git, drafting, approval, and administration surfaces stay lawyer-only.

Provider setup and parity across deployment rows

The infrastructure command creates cloud resources; an accountable operator must still authorize provider accounts, contracts, domains, and organization access. Treat each deployment row as a separate provider attachment. Store row identities and public coordinates in its external config.toml; store credentials in its encrypted secrets.enc.yaml. The approved operator system supplies the row-to-provider mapping. The source repository contains no provider IDs, callback host map, organization slugs, or per-row operational checklist.

For browser sign-in, configure one OAuth client per row and derive its exact callback from that row's NAVIGATOR_PUBLIC_HOST (/auth/callback). Keep each client restricted to its own host and project. Store its client ID in the external config and its client secret in the encrypted secret file. Provider consoles may require an authorized human to set consent branding, audience, and test users; the CLI cannot establish those approvals.

For repository access, create an organization-owned application with only the repository permissions the installation needs. Keep the organization, application ID, and installation identity with the selected private row; keep its private key encrypted. Do not reuse one row's application credentials or webhook secret in another row. Apply the principle of least privilege and review the installation scope with the organization's owner.

Rotate credentials at the provider first, then write the replacement directly into the selected row's encrypted file with sops. Synchronize through the CLI using the same external root, then verify the row's provider smoke test. Never place plaintext credentials in Git, issue text, chat, screenshots, or shell history. A dry-run can check names and local configuration, but it cannot prove that a provider account, nonempty credential, contract, or callback is valid.

Provider-specific accounts may require human approval, paid plans, domain verification, delegated Workspace authority, or production eligibility. Keep those decisions and their evidence in the approved operator system. Use synthetic data for smoke tests and verify that each test remains confined to the selected row's external resources.

The external surface — every third party, in one place

Neon Law Navigator's runtime external surface has these services, in two kinds — platform services (the cloud the stack runs on) and feature vendors (each lights up one capability and stubs out cleanly when unconfigured):

The two service deployments

A production install runs one Rust application in two operational roles:

• navigator-web — the public portal, Navigator MCP/API routes, webhooks, health probes, embedded Rego authorization, and client-facing Documents/Engagements/Invoices views.
• workflows-service — the durable Restate worker that renders documents, advances workflows, sends emails, and runs the background side effects the portal schedules.

The split keeps the portal stateless: every side effect that needs durable retries belongs to the worker rather than to a request handler. Lawyer and admin users with Project access work the matter through the firm workbench, over the participation-scoped list that surface resolves for them. Clients use the portal file surface: they see only Projects where they have a person_project_roles row, and the portal renders reviewed documents, Engagements, and invoices without exposing storage vocabulary or GCS credentials.

Security architecture

flowchart TB
  client["Client browser"]
  lawyer["Lawyer/admin browser"]
  oidc["OIDC provider"]
  edge["HTTPS Gateway"]

  subgraph gke["GKE namespace"]
    web["navigator-web\nportal, Navigator MCP, APIs"]
    worker["workflows-service\nDurable worker"]
  end

  subgraph data["Private data plane"]
    pg["SurrealDB\nroles + project access"]
    docs["GCS documents bucket\nprivate blobs"]
    assets["GCS assets bucket\nprivate marketing objects\nserved through /assets"]
  end

  client --> edge
  lawyer --> edge
  edge --> web
  web --> oidc
  web --> pg
  web --> docs
  web --> assets
  web --> worker
  worker --> pg
  worker --> docs

  client -. "portal session only" .-> web
  lawyer -. "portal session + lawyer role" .-> web

Clients never receive GCS IAM, bucket URLs, or object paths. A client request enters through navigator-web, resolves identity through OIDC, reads authorization from persons and person_project_roles, and streams only the portal-visible matter files back through the app. Lawyer and admin access is not a second door: it enters through the same service and the same database access model, and differs only in what the role and participation checks allow.

Ship and verify

Provisioning gives you an empty cluster; now pin one deployment to one published release. The --deployment flag selects the private row that supplies its project, cluster context, namespace, image name, hosts, buckets, SQL instance, required browser OAuth client, and runtime Secret name. First-install order is load-bearing: apply the deployment's Secret Manager objects, install observability so navigator-otel-env exists, render the release, then apply it:

Before shipping from a checkout whose deployment changes have not reached your installed binary, install that checkout's CLI. A stale global binary may enforce an obsolete ship contract even when the selected deployment's config correctly carries the current production profile:

cargo install --path cli --force

An operator wrapper must make the same guarantee before it changes Kubernetes or GCP: build the selected checkout's cli package, then prove that navigator ops secrets apply --help exists. Do not fall back to an arbitrary pre-existing target/release/navigator; a stale binary can lack a subcommand the current runbook requires and stop only after it has already refreshed cluster credentials. Browser OAuth values belong in the deployment's tree before the wrapper starts, so preparation is non-interactive. Keep explicit confirmations only for irreversible resource retirement and the live release roll.

The failed guard runs before manifest rendering or cluster mutation. Install the matching CLI, set both environment and credential profiles to production in the deployment's config.toml, then run the complete sequence:

navigator ops secrets apply --deployment "$ROW" --deployments-dir "$NAVIGATOR_DEPLOYMENTS_DIR"

navigator ops observability --deployment "$ROW" --deployments-dir "$NAVIGATOR_DEPLOYMENTS_DIR"

navigator ops ship --deployment "$ROW" --deployments-dir "$NAVIGATOR_DEPLOYMENTS_DIR" --tag YY.M.D --dry-run

navigator ops ship --deployment "$ROW" --deployments-dir "$NAVIGATOR_DEPLOYMENTS_DIR" --tag YY.M.D \
  --image-digests "$IMAGE_DIGESTS"

ops observability is safe before the application Deployments exist: it creates the namespace-scoped collector and navigator-otel-env ConfigMap, then skips the optional Deployment patch because ops ship renders that wiring into new Deployments. A cold Autopilot cluster may take several minutes to create its first nodes and start the managed Prometheus admission webhook. The CLI retries an idempotent IAM binding while a new navigator-otel Google service account propagates. Before it applies collector-monitoring.yaml, the Rust CLI uses Google ADC and the Container API to read the selected GKE cluster endpoint and CA, then queries the managed gmp-operator Endpoints object with its Kubernetes client. It waits only while that object has no ready addresses; a RUNNING GKE cluster is not treated as proof that the admission webhook is ready. The endpoint wait is bounded to three minutes and prints each attempt. If it expires, inspect the managed operator rather than deleting the collector or patching the Secret:

kubectl --context "$NAVIGATOR_GKE_CONTEXT" -n gke-gmp-system \
  get deployment,pods,endpoints gmp-operator

When the managed operator becomes ready, rerun the exact same navigator ops observability or three-deployment operator command. Namespace creation, Secret reconciliation, Google service-account creation, IAM bindings, and collector manifests are all idempotent; a partially completed first run is a resume point, not a cleanup instruction.

The staging dogfood run also proved two quota-independent defaults. Autopilot clusters are created with --enable-private-nodes, so a new region does not need one public in-use address per node. The link-out compatibility writer uses the standard persistent-disk class, not an SSD-backed class; it must not consume SSD_TOTAL_GB for an otherwise empty mount.

Drive it from the CLI

Once your instance answers /readyz, the navigator CLI runs the firm's whole matter flow against it from your terminal. It authenticates like gcloud auth login and lands a short-lived (~8h) token at ~/.navigator.json:

cargo install --path cli          # installs `navigator` on your PATH
# …or skip installing — run it straight from the source tree:
cargo run -p cli -- login --host www.your-domain.example   # `cargo run -p cli -- <args>` == `navigator <args>`

Make it yours — white-label under your own brand

Neon Law Navigator runs three registered brands from one binary. A deployment operator can ship it under another identity without forking source by describing the organization once in a private navigator.yaml bundle:

cp cli/tests/fixtures/navigator.example.yaml navigator.yaml   # then edit: names, emails, domain, logos
cargo run -p cli -- ops rebrand build --out .devx/brand-bundle   # deprecated compatibility command
cargo run -p cli -- ops rebrand verify --dir .devx/brand-bundle   # deprecated compatibility command
set -a; source .devx/env; set +a                # object storage and the rest of the runtime env
NAVIGATOR_CUSTOM_BRANDING=.devx/brand-bundle cargo run -p neon

First-ship lessons

A first ship to a cold cluster can expose ordering assumptions. Secret preflight, namespace creation, CSI projection, cluster add-ons, and Restate registration each have distinct readiness requirements. Follow the current navigator ops command sequence and stop when a preflight fails; do not seed plaintext Secrets or bypass CLI checks with manual cluster commands.

Before a live ship, confirm that the selected row's approved external configuration contains the required encrypted secret objects and capability settings, that its image exists, and that cluster add-ons needed by admission are ready. The offline example plan does not perform those live checks. After a real ship, verify rollout, Restate registration, /readyz, /version, certificate readiness, DNS, and the browser surface before recording completion.