oxygen: Instructions file for Claude Code

Claude Code Assistant Guidelines

Injected into every API call, together with product-context.md and internal-docs/backend-architecture.md (both @-imported below). State each rule once, in the section that owns it. A recap section is how three copies of the --local rule accumulated here; if a rule feels worth repeating, the first statement is the one to sharpen. Anything retrievable by reading the code in a minute belongs in the code or a crate-local CLAUDE.md, not here.

Oxy (brand: Oxygen) is a Rust workspace + web frontend. The oxy CLI/server binary lives in the server crate (oxy-server, the default workspace member) — a thin composition root that mounts API surfaces over the app crate (oxy-app), the CLI + HTTP-server library where almost all the code lives.

• Rust · async Tokio · ORM Sea-ORM (PostgreSQL) · HTTP Axum
• Frontend Vite + React + TypeScript, pnpm (never npm/yarn)

Workspace Layout

crates/
  server/                   # (oxy-server) the `oxy` BINARY — composition root (main.rs + router
                            #   assembly) that mounts the API surfaces. Default member.
  app/                      # (oxy-app) CLI + HTTP server LIBRARY (the bulk of the code; lib-only)
  api-<context>/            # (oxy-api-*) HTTP surface crates oxy-server mounts — one bounded context
                            #   each; oxy-app does NOT depend on them. Placement rules S1–S7 and the
                            #   per-crate review: internal-docs/domain-boundaries.md
  route-catalog/             # (oxy-route-catalog) generated GET /api/_catalog table; sits ABOVE oxy-app
                            #   so a surface edit doesn't rebuild oxy-app. oxy-server hands it in
  app-dylib/                # (oxy-app-dylib) dev-only dynamic-linking shim, EXCLUDED from the
                            #   workspace; built only by `--features dev-dynamic` (just dev-backend-dyn)
  app-core/                 # (oxy-app-core) Shared app-layer seam: audit, serve_mode,
                            #   org/custom-app subdomain dispatch, member authz
  tenancy/                  # (oxy-tenancy) Tenancy domain logic shared across contexts: org teams +
                            #   app-access grants. Below oxy-app and the api-* surfaces; no routes
  core/                     # (oxy) Core platform library, published as "oxy"
  auth/                     # (oxy-auth) Authentication — who you are
  authz/                    # (oxy-authz) Authorization — what you may do. THE authority model
  entity/  migration/       # Sea-ORM entities / migrations
  semantic/                 # (oxy-semantic) Semantic query layer (airlayer)
  shared/                   # (oxy-shared) Shared types, errors, infra
  project/                  # (oxy-project) Project/model config domain
  oxy-compile/              # (oxy-compile) Compile boundary: workspace FS → Postgres rows
  workspace-fs/             # (oxy-workspace-fs) Workspace filesystem helpers (thin)
  git/                      # (oxy-git) Git client / worktree ops
  platform/                 # (oxy-platform) Platform services
  billing/                  # (oxy-billing) Stripe billing
  metric-monitoring/        # (oxy-metric-monitoring) Anomaly monitors / metric tree
  observability/            # (oxy-observability) Customer-facing observability backend
  telemetry/                # (oxy-telemetry) Platform telemetry: OTLP traces+logs → cluster OTel
                            #   collector (ClickStack/HyperDX), stderr JSON format, HTTP request spans
  airform/                  # (oxy-airform) dbt-style modeling
  airhouse/                 # (airhouse) Warehouse + connector
  cameras/                  # (oxy-cameras) Camera fleet domain
  test-utils/               # (oxy-test-utils) Fixtures & mocks
  agentic/
    core/ runtime/ pipeline/ analytics/ builder/ automation/ airway/
    connector/ http/ llm/ semantic/    # see crates/agentic/CLAUDE.md for layering
  infrastructure/llm/oxy-llm
  infrastructure/semantic/  # (oxy-airlayer-compat) airlayer compatibility shim
  integration/{looker,unifi,omni}
web-app/                    # Frontend (see web-app/CLAUDE.md)
sdk/cli/                    # (@oxy-hq/cli) the `oxyc` CLI — the gh-api-style client for
                            #   the HTTP API, plus the customer-account tooling. TypeScript,
                            #   NOT Rust: it replaced `oxy api`, which was deleted from
                            #   crates/app. See internal-docs/oxy-api-cli.md
sdk/cli/skills/             # THE Oxy platform skills — published to oxy-hq/skills and installed
                            #   by customers' agents. Update one in the PR that changes the
                            #   behaviour it describes. internal-docs/platform-skills.md