navigator

Turn a dirty working tree into a clean pull request against `main`: survey every change, group the files into Conventional Commits by blast radius (one concern per commit), run the gate, branch off `main`, capture a visual for any user-visible change, push, and open the PR. Trigger when the user says "/create-pr", "create a PR", "open a pull request", "commit and PR these changes", "group these into commits and ship them", or has a dirty working tree they want landed. Stops at "PR open"; building images and deploying to prod is a separate flow.

Workspace Rust guardrails. Trigger on the sharpest moments: a change that adds `unsafe`, `unwrap`, `expect`, or `panic!` outside `main()`/tests; introducing a new public API, error type, or module; reaching for a different web framework, ORM, or async runtime (we standardize on Axum + SeaORM + Tokio); or wiring a new binary's `main()`. Read [`docs/rust-programming.md`](../../../docs/rust-programming.md) before acting — it is the authoritative reference.

Embed a local screenshot or GIF into a GitHub PR (or issue) body so it actually RENDERS on github.com, driven from the CLI — no drag-drop, no committing the file, no image-hosting branch, no release/tag. It uploads the `/tmp` capture to GitHub's native `user-attachments` CDN via the `gh-image` extension (which borrows your logged-in github.com browser session) and returns a real `https://github.com/user-attachments/assets/…` URL to drop into the body. Trigger as the embed half of [[create-pr]] Step 6 (after [[web-preview]] captures the visual), when a reviewer comment on a PR asks for a "live walkthrough"/screenshot during [[review-pr]], or any time you have a `/tmp` image that must appear in a PR/issue body or comment. This is the LOCAL/`gh` path for hosting and embedding a capture. Capture lives in [[web-preview]] — a walkthrough defaults to a GIF of the real interaction (§5), a still (§3) only for a genuinely static change; this skill only hosts + embeds it.

Run the `web` app locally against the KIND dependency stack and look at it in a real browser — the canonical "spin up web, drive Chrome, capture to /tmp, verify" loop. Trigger whenever asked to run, preview, screenshot, or visually verify `web` / a page / a UI change, to "open the design page", "check it in chrome", or to prove a front-end behavior (syntax highlighting, a toast, a layout, a keyboard shortcut) actually renders. A PR walkthrough defaults to a GIF of the real interaction (§5); a still is only for a genuinely static change. This is the browser half of the local loop; `kind-local-dev` is the cluster half it builds on. Skip for pure logic/unit work — `cargo test` uses testcontainers and needs no cluster.

Local Kubernetes-in-Docker (KIND) workflow for the navigator workspace — cluster lifecycle, ingress, port-forwarding, the "host runs `web`, deps run in cluster" iteration pattern via the `navigator` CLI. Trigger when running any `navigator` orchestration subcommand (`dev up`, `dev down`, `dev deploy`, `dev kind up`, `dev kind down`, `dev e2e`, `dev logs`, `dev worktree-env`), editing `k8s/kind-config.yaml`, debugging an in-cluster service from the host, or onboarding the cluster from a fresh machine. Also trigger before installing a different local-Kubernetes flavor — we standardize on KIND. Also trigger before proposing to run, preview, screenshot, or manually exercise the app, or before any action that runs on the user's machine (cluster, browser, or cloud commands) — those resolve to this KIND loop, and the move is to propose the commands for the user to run.

Address a requested pull-request comment against the real code at the PR head. Read the thread, source, and covering test; reproduce behavioral claims in the right KIND-backed environment; apply only the minimum valid fix; prove it; then reply and resolve that thread. Trigger when the user asks to address or review a PR comment, a Greptile finding, or a named review thread. For a request covering several comments, repeat this narrow action for each one without combining their scopes.

Twelve-perspective review pattern for the people the firm serves ("The Client Council") — the demand-side sibling of the engineering `/council` (the people who *build* Neon Law Navigator) and the `legal-council` (the counsels who *draft* it). Each voice fuses a zodiac stance with a real client walking in the door across the firm's practice areas — Libra the prospective client at the threshold chairs (weighs whether to hire a lawyer at all, then closes on "does this make me walk in and stay?"), Aries the tenant facing eviction names the fire, Pisces the overwhelmed person who almost didn't reach out guards access-to-justice, Capricorn the elder planning their legacy thinks in decades, Leo the wronged client who wants to sue tests the firm's featured litigation practice, and so on. Use it when building Neon Law Navigator — intake flows, questionnaire prompts, pricing copy, portal UX, onboarding — to pressure-test "does this actually serve the human who shows up?" Trigger when the user says "client council", "cu

Authoring rules for client-facing marketing copy on neonlaw.com — firm pages under `web/content/marketing/`, the views under `views/src/pages/`, and any public surface where the firm advertises services (LinkedIn posts, YouTube content, talk titles when speaking *for the firm*). Trigger when adding or editing any of those files, drafting a hero line, naming a new service tier, writing a service description, or quoting a fee. Three load-bearing rules: (1) market only the firm's own value, never compare to or characterize "other lawyers / traditional firms"; (2) no hyperbole or unsubstantiable superlatives; (3) attorney-advertising compliant across the firm's bar admissions (CA, NV, WA) — no guarantees of results, no certification claims for SOC 2 / HIPAA, SLAs are service commitments not outcome promises. Skip for non-marketing surfaces (internal docs, code comments, ADRs) and for already-binding documents (signed retainers, filed pleadings) — those are reviewed by the attorney of record, not by this skill.

Twelve-perspective architectural review pattern ("The Council of Twelve"), each voice fusing a zodiac stance with a practitioner identity — Virgo the engineering manager chairs the council (opens with the framing, closes with consensus + action), Aries the incident commander names the gap, Scorpio the security/trust engineer cuts to the core, Aquarius the network/platform engineer surfaces the systems pattern, Cancer the new-hire applies beginner's mindset, Capricorn the graybeard guards long-term maintainability, Sagittarius the PM keeps the big picture, and so on. Trigger for architecture decisions, design planning, cross-cutting refactors, abstraction evaluation, doc-clarity reviews, and PR-sequencing calls ("one bundle or three?"). Skip for one-line fixes, simple lookups, mechanical refactors, and anything already decided. Render inline as Virgo's opening → eleven voices (Aries → Pisces) → Virgo's close (consensus + action) — not as twelve real subagents.

Twelve-perspective copy-review pattern for legal drafting ("The Legal Council" — a *council* (c-o-u-n-c-i-l, a group) of the firm's *counsels* (c-o-u-n-s-e-l, the attorneys): a council of counsels. AIDA is the agent that carries the tool, not the name of the council; the sibling engineering review at `/council` is the other council). Each voice fuses a zodiac stance with a distinct lawyer's background — Capricorn the managing partner leads, Scorpio the ethics counsel cuts to the core, Leo the immigration defender boldly speaks for the client whose right to stay is on the line, Cancer the legal-aid / tenant-defense attorney reads as the applicant going through deep struggles yet bold enough to seek counsel, Sagittarius the public-interest advocate ties back to the mission, and so on. The bench covers the major practice areas the firm handles (LLC formation, trust, will, tenant defense, immigration, annual report, NV tax filings) with intentional weight toward access-to-justice perspectives. This council shapes

The standard recipe for adding a new legal workflow to Neon Law Navigator — feature spec first, then template + questionnaire, then a Restate-durable workflow composed from a shared step library (staff review, signature, certified mail, e-filing, county / Nevada SoS / Department of Taxation filings). Trigger when adding any new legal matter type (LLC formation, trust formation, will, retainer variant, dissolution, annual report, tax filing), extending an existing template's workflow with new states, or introducing a new step prefix (`filing__nv_sos`, `e_filing__*`, `certified_mail`, `generate_pdf`). Also trigger before reaching for a one-off router handler — legal flows belong in the template + workflow YAML so they are auditable and reusable. Also trigger when vendoring or mapping a government PDF form (`navigator forms sync` / `forms re-author`, a `.fields` map under `templates/forms/`) — that PDF layer is part of the same legal-form contribution; the mechanics live in `docs/gov-forms.md`.

Lint every `.md` file in the workspace with the navigator CLI (M-family rules + S101 120-char line limit). Trigger when adding or editing any Markdown file (READMEs, `docs/`, `CLAUDE.md`, blog posts under `web/content/`) and before committing `.md` changes. Dogfood the workspace's own binary; never hand-roll a different linter.

The operational contract for Neon Law Navigator's Restate-backed durable execution — how to keep the running workflows alive, diagnose why one didn't fire, and not break them. Covers the submit-vs-run split (workflows lib / workflows-service bin), the service inventory, the six-hourly Heartbeat liveness canary, the three start modes, and how to investigate a stalled workflow by following the evidence — commit history, GitHub Actions runs, pod and Cloud logs, and Google Cloud (Trace, GKE, the Restate console) — then pin the fix with a guard test so it can't recur. Trigger when touching workflows-service, a *-trigger CronJob, the image Containerfiles, when re-registering with Restate, when a scheduled or manual workflow "didn't run", or when adding a workspace crate (it must enter the Containerfile COPY lists). This engine executes BINDING legal artifacts (retainer dispatch, signatures, filings, the matter-close invoice), so an outage is a diligence concern, not a backlog item. Debugging surfaces carry invocati

`navigator dev up` stands up the KIND stack with Grafana LGTM (Loki logs + Tempo traces + Prometheus metrics + a bundled OTel Collector) so you can actually SEE the telemetry every Neon Law Navigator binary emits — it wires both in-cluster and host-side `web` to export to it and port-forwards Grafana to the host. Trigger when asked to "see traces locally", "test OTel output", "check logs/metrics/traces in Grafana", "is my span showing up", to debug a cross-service trace (`web` to Restate to a workflow handler), or to verify a new metric/span before it ships to prod. This is the LOCAL viewing loop; the emit-side seam (how to ADD a span/metric/log and the no-content rule) is the `observability` skill, and the prod landing (Cloud Trace / Cloud Logging / BigQuery) lives there too.

How Neon Law Navigator emits telemetry and how to debug a durable-execution failure fast. Every binary shares one seam, `telemetry::init` (stdout logs — JSON in prod — plus OTLP traces + metrics when `OTEL_EXPORTER_OTLP_ENDPOINT` is set), and everything lands in BigQuery (structured logs via a Cloud Logging sink; traces/metrics via an OTel Collector to Cloud Trace/Monitoring). Trigger when adding a span/metric/log field, instrumenting a handler or workflow, wiring a new binary's main, debugging a missing nightly/periodic job or a silent trigger, running `navigator ops doctor`, or touching the OTel Collector / BigQuery sink. THE ONE RULE, stated first because it is load-bearing: instrument identifiers and counts, NEVER content — a notation_id, service, outcome, duration, status code are fine; a client name, answer body, email address, or document body must never enter a span, metric, or log. Telemetry crosses the firm's trust boundary; client content does not. Skip for one-off println debugging.

Neon Law Navigator's role + participation authorization model — the **canonical answer** to "who can see what." Every person carries exactly one role in `persons.role` (`client`, `staff`, or `admin`); per-project scope lives separately in `person_project_roles.participation`. Admin bypasses project-scoping silently. Trigger when the user mentions any of `role`, `roles`, `staff`, `client`, `admin`, `participation`, OPA, "who can see", "what does Libra/Nick see", or before adding a new authz check anywhere in `web`. Also trigger when reaching for a JSON-array `roles[…]` shape — the schema collapsed to a single `role` column in migration `m20260619_collapse_persons_roles_to_role`, and the doc/PR drift to fix is to use the singular column.

Render the workspace ERD as SVG (the canonical `docs/erd.svg`) using the navigator CLI's deterministic, pure-Rust renderer. Trigger when prepping a slide, screenshot, design-doc, or external review — or when someone asks "can you show me the database structure?" Also trigger when a migration has just landed: regenerate both `docs/erd.md` (mermaid) and `docs/erd.svg` (rendered) so picture and schema stay in sync; the `cli::tests::erd_svg` integration test will otherwise fail.

Keycloak as the local OIDC identity provider for `web` — realm/client config, Authorization Code + PKCE flow, JWKS verification, id_token decoding, and the persons-table linking story. Trigger when editing `k8s/overlays/kind/deps/keycloak.yaml`, changing the OIDC client config, debugging the `/auth/callback` handler, touching the `oauth2` or `jsonwebtoken` crates, or planning a swap to a different OIDC provider (Google Cloud Identity, Auth0). Identity providers are pluggable — code paths must stay spec-compliant.

Open Policy Agent (OPA) as the authorization decision point for `web` — sidecar deployment, REST query API, Rego policy authoring, ConfigMap-bundled policies, hot reload. Trigger when editing `k8s/base/opa/opa.yaml`, writing or modifying Rego, touching the OPA middleware in `web` (`web::policy::require_policy`), setting `NAVIGATOR_OPA_URL`, or adding a new `/portal/...` route that needs policy enforcement. Also trigger before reaching for a role-based authorization library — we route authz through OPA.

How to AUTHOR a Restate handler in Rust (`restate-sdk` 0.10) without breaking durability — the determinism and error-handling contract that makes `workflows-service` replay-safe. Distilled from Restate's own `building-restate-services` skill (https://github.com/restatedev/skills), retargeted from its TS/Python/Java/Go examples to this workspace's Rust SDK and grounded in `workflows-service/src` (the only `restate-sdk` consumer). THE ONE RULE, load-bearing: every non-deterministic act — clock (`Utc::now`), randomness, UUIDs, a DB write, object storage, any network/IO call — must happen INSIDE `ctx.run(...)`, which journals the outcome so a replay reuses the recorded value instead of re-executing. Bare non-determinism in handler body = a replay that diverges from the journal = corrupted durable state. Trigger when adding or editing a handler in `workflows-service`, reaching for `#[restate_sdk::object]` / `#[restate_sdk::workflow]` / `#[restate_sdk::service]`, calling `ctx.run` / `ctx.get` / `ctx.set` / `ctx.sle

Turn a raw list of organizations and the people who work at them into a valid Neon Law Navigator bulk-import payload, then load it through the shared `import` engine: the `cli import-contacts` command, the `aida_bulk_import` MCP tool, or the web upload route. Use this when someone hands you a contact list (names, emails, titles, phone numbers, org names) and wants those people and their organizations created as `persons` and `entities` with the links between them. Trigger on "bulk import these contacts", "load this list of people and orgs", or "create these as clients", or when AIDA is asked to add several people at once. The contract and rules live in `docs/bulk-contact-import.md`; this skill is the LLM-facing recipe for producing the JSON and choosing the surface. Skip for a single person (use `aida_create_person`) or for opening a matter/Project (the per-engagement onboarding flow, not this importer).