docs: update project docs, add license, and document namespace design

Add Elastic License 2.0 (ELv2). Document attribute namespace design
(flat in expressions, nested in API) across permission-system docs and
proxy/admin-ui CLAUDE.md files. Update roadmap to replace frontend
architecture plan with Catalyst adoption strategy. Add general rules
(no hardcoded secrets, TDD, test suite) and conventional commit format
to project instructions.

Author: jumpbetweenrows

.claude/CLAUDE.md

@@ -32,6 +32,11 @@ git config core.hooksPath .githooks
 
 Use `/release` to prepare the changelog, bump versions, commit, and tag. Use `/commit` for day-to-day commits.
 
+## General Rules
+- **Never hardcode secrets** — API keys, passwords, credentials, and tokens must come from environment variables or encrypted config, never literals in source code.
+- **Run the full test suite before considering a task complete** — `cargo test` for proxy, `npm run test:run` for admin-ui. Don't declare done until tests pass.
+- **TDD for all new code** — write failing tests first, then implement until they pass. This applies to new features and bug fixes alike, not just the bug fix protocol.
+
 ## Planning & Feature Design
 
 ### Design-First, Discuss Before Building

.claude/commands/commit.md

@@ -14,4 +14,9 @@ description: Create a git commit
 
 Based on the above changes, create a single git commit.
 
+Use conventional commit format: `type(scope): description`
+- Types: feat, fix, refactor, test, docs, chore, ci, perf, style
+- Scope is optional but preferred (e.g., `proxy`, `admin-ui`, `migration`)
+- Description should be lowercase, imperative, no period
+
 You have the capability to call multiple tools in a single response. Stage and create the commit using a single message. Do not use any other tools or do anything else. Do not send any other text or messages besides these tool calls.

LICENSE

@@ -0,0 +1,91 @@
+Elastic License 2.0 (ELv2)
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set
+of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company
+makes such a claim, your patent license ends immediately for work on behalf
+of your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license
+no later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is
+the software the licensor makes available under these terms, including any
+portion of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or
+the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

admin-ui/CLAUDE.md

@@ -33,11 +33,21 @@ React 19, Vite 7, Tailwind 4, TanStack Query 5, react-router-dom 7, Vitest 4, @t
 - `src/pages/AttributeDefinitionEditPage.tsx` — Create/edit attribute definitions (exports `AttributeDefinitionCreatePage` and `AttributeDefinitionEditPage`). Uses `AttributeDefinitionForm` component with standard card wrapper + back button layout.
 - `src/components/AttributeDefinitionForm.tsx` — Reusable form for attribute definition create/edit (matches `RoleForm`/`DataSourceForm` pattern). Supports value types: string, integer, boolean, list.
 - `src/components/UserAttributeEditor.tsx` — Inline editor for user attributes on UserEditPage. Loads attribute definitions to show type-appropriate inputs (text, number, boolean toggle, enum dropdown, tag/chip input for lists, multi-select checkboxes for lists with allowed values). Shows `{user.KEY}` syntax hint per attribute.
+- `src/components/ExpressionEditor.tsx` — CodeMirror-based expression editor for filter/mask expressions
+- `src/components/PolicyCodeView.tsx` — Read-only policy code preview
+- `src/components/UserAssignmentPanel.tsx` — User-scoped policy assignment panel
+- `src/components/UserForm.tsx` — Reusable user create/edit form
+- `src/components/Layout.tsx` — App shell layout with sidebar navigation
+- `src/pages/PoliciesListPage.tsx` — Paginated policy list
+- `src/pages/PolicyCreatePage.tsx` — Policy creation page
+- `src/pages/PolicyEditPage.tsx` — Policy edit page with form + assignment panel
+- `src/pages/QueryAuditPage.tsx` — Query audit log viewer
 - `src/test/test-utils.tsx` — `renderWithProviders` (QueryClient + AuthProvider + MemoryRouter)
 - `src/test/factories.ts` — `makeUser`, `makeDataSource`, `makeDataSourceType`, `makeDiscoveredSchema/Table/Column`, `makeDecisionFunction`, `makePolicy`, `makePolicyAssignment`
 
-## Running Tests
+## Running
 ```bash
+npm run dev        # start dev server (proxies /api → localhost:5435)
 npm run test:run   # single run (CI)
 npm test           # watch mode
 ```

docs/permission-system.md

@@ -317,6 +317,25 @@ Reserved keys for `entity_type = "user"`: `tenant`, `username`, `id`, `user_id`
 - An empty list `[]` expands to a single `NULL` literal: `department IN (NULL)` → evaluates to false (no rows match).
 - In decision function context, list attributes appear as JSON arrays: `ctx.session.user.departments` → `["engineering", "security"]`.
 
+### Namespace design: flat in expressions, nested in API
+
+User attributes live at two different levels depending on the context:
+
+| Surface | How attributes appear | Example |
+|---|---|---|
+| **API payloads** (create/update/response) | Nested under `attributes` | `{ "attributes": { "region": "us-east" } }` |
+| **Template variables** (filter/mask expressions) | Flat under `user` | `{user.region}` |
+| **Decision function context** | Flat under `user` | `ctx.session.user.region` |
+| **CLI config (future YAML)** | Nested under `attributes` | `attributes: { region: us-east }` |
+
+This is intentional:
+
+- **API/storage nests** because attributes are a distinct concern from built-in fields (`username`, `tenant`, `is_admin`). They have different validation rules, full-replace semantics, and are governed by attribute definitions. Nesting makes the API self-documenting about what is user-defined vs. built-in.
+- **Expressions/context flatten** because policy authors write these constantly and brevity matters. `{user.region}` and `ctx.session.user.region` are cleaner than `{user.attributes.region}`.
+- **Reserved key validation** prevents collisions — attribute keys cannot shadow built-in fields, and built-in fields always take priority at runtime.
+
+The rule is simple: **define attributes under `attributes`, reference them as `{user.KEY}`**.
+
 ### Setting attributes on users
 
 User attributes are stored as a JSON column on the user record. They are set via `PUT /api/v1/users/{id}` with an `attributes` field:
@@ -450,7 +469,7 @@ function evaluate(ctx, config) {
 
 `time.now` is an ISO 8601 / RFC 3339 timestamp representing the **evaluation time** — the moment the context is built. For visibility-level functions this is when the connection context is computed; for query-level functions it is when the query is processed. This enables time-windowed decision functions (e.g., break-glass temporary access).
 
-Custom user attributes are flattened as first-class fields on the `user` object with correctly typed values (string/number/boolean/array). List attributes appear as JSON arrays of strings. Built-in fields (`id`, `username`, `tenant`, `roles`) always take priority. See [User Attributes (ABAC)](#user-attributes-abac) for details.
+Custom user attributes are flattened as first-class fields on the `user` object with correctly typed values (string/number/boolean/array) — e.g., `ctx.session.user.region`, not `ctx.session.user.attributes.region`. This matches the flat `{user.KEY}` namespace used in template variables. In the API, the same attributes are nested under `attributes` (see [Namespace design](#namespace-design-flat-in-expressions-nested-in-api)). List attributes appear as JSON arrays of strings. Built-in fields (`id`, `username`, `tenant`, `roles`) always take priority. See [User Attributes (ABAC)](#user-attributes-abac) for details.
 
 **Visibility-level enforcement**: `column_deny`, `table_deny`, and `column_allow` policies are enforced at connect time (visibility level) by removing columns/tables from the per-user schema. Decision functions on these policy types are evaluated at visibility time when `evaluate_context = "session"`. If the decision function returns `fire: false`, the policy is skipped and the column/table remains visible. For `evaluate_context = "query"`, the policy's visibility effect is skipped entirely (deferred to query time), since query metadata is not available at connect time — the column/table stays visible in the schema and the decision function runs at query time as normal.
 

docs/roadmap.md

@@ -433,39 +433,31 @@ Given complexity of new policy system (interaction with DataFusion and PostgreSQ
 - Proposed: Modify hook to only check staged changes using `git diff --staged` or `git diff --cached`
 - This preserves ability to have WIP changes without them interfering with the commit process
 
-## Frontend Architecture Guideline: Future-Proofing UI
+## Frontend Architecture: Tailwind Plus Catalyst Adoption
 
-### 1. Decouple Logic from Presentation
+### Approach
 
-Pattern: Use Custom Hooks (e.g., useAuth, useCart) to handle all API calls, state management, and business logic.
+Adopt Tailwind Plus Catalyst as the UI component foundation. Catalyst provides accessible, well-designed React components built on Headless UI + Tailwind CSS v4. Components are copied into the project as source code — no runtime dependency on Catalyst itself.
 
-Rule: Components should only receive data and functions via props. If we want to swap a "List View" for a "Card View" later, the logic hook remains untouched.
+### Setup
 
-### 2. Implement a "Headless" Design System
+- **Full kit**: `admin-ui/catalyst-kit/` (gitignored) — complete Catalyst download for reference
+- **Active components**: `admin-ui/src/components/ui/` — only components in use, copied from the kit as needed
+- **Dependencies**: `@headlessui/react`, `motion`, `clsx`, `@heroicons/react`
+- **Router integration**: `src/components/ui/link.tsx` — wraps `react-router-dom` `Link` for Catalyst compatibility
+- **Docs**: https://catalyst.tailwindui.com/docs/{component-name}
 
-Tooling: Use CVA (Class Variance Authority) to manage Tailwind variants.
+### Migration Strategy
 
-Rule: Avoid hardcoding "messy" Tailwind strings directly in feature components. Define styles as Variants (e.g., intent: "primary", size: "lg") in a central UI folder.
+Incremental, page-by-page — no big-bang rewrite. Swap raw HTML elements for Catalyst components alongside feature work:
+1. Core primitives first: Button, Input, Select, Textarea, Checkbox
+2. Layout: Sidebar layout, Navbar (replaces current `Layout.tsx`)
+3. Data display: Table, Badge, Description list, Dialog
+4. Forms: Fieldset, Radio, Switch, Combobox, Listbox
 
-Goal: Changing the "Look" of the app should involve editing one tailwind.config.js or a few CVA files, not hunting through 50 feature components.
+### What This Replaces
 
-### 3. Strict Design Token Usage
-
-Rule: Zero Hex Codes in components. All colors, spacing, and border-radii must come from the tailwind.config.js theme.
-
-Standard: Use semantic naming. Instead of text-blue-600, use text-brand-primary. When v2 arrives, we change the value of brand-primary in one place.
-
-### 4. Component Categorization (Atomic Design)
-
-UI Components (/components/ui): Low-level, stateless elements (Buttons, Inputs, Modals). Use libraries like Radix UI or Headless UI for accessibility logic so we only have to worry about the CSS.
-
-Feature Components (/features/): High-level components that use the UI pieces to solve a business need (e.g., PaymentForm).
-
-### 5. Utility for Class Merging
-
-Requirement: Use a cn() helper function (combining clsx and tailwind-merge).
-
-Benefit: This ensures that if we need to override a "v1" style for a specific edge case, the classes merge correctly without CSS conflicts.
+The previous plan (CVA, Atomic Design, strict design tokens, `cn()` helper) is superseded. Catalyst provides variant management, accessible primitives, and consistent design out of the box. No additional abstraction layers needed at the current scale (~25 pages, ~29 components).
 
 ## Policy History & Audit Improvements
 

proxy/CLAUDE.md

@@ -25,7 +25,7 @@ pgwire 0.38, DataFusion 52, axum 0.8, SeaORM 1, tokio-postgres 0.7, argon2 0.5,
 - `src/entity/attribute_definition.rs` — SeaORM entity for the `attribute_definition` table (id, key, entity_type, display_name, value_type, default_value, allowed_values, description). Includes `validate_value()` and `parse_allowed_values()`.
 - `src/admin/attribute_definition_handlers.rs` — CRUD endpoints for attribute definitions (`GET/POST /attribute-definitions`, `GET/PUT/DELETE /attribute-definitions/{id}`). Supports `?entity_type=user` filter and `?force=true` cascade delete via database-specific JSON operations (SQLite `json_remove()`, PostgreSQL `jsonb -`). Includes `validate_json_path_key()` defense-in-depth before SQL interpolation. Update handler invalidates caches when `value_type` changes.
 - `src/crypto.rs` — AES-256-GCM `encrypt_json` / `decrypt_json`
-- `../migration/src/lib.rs` — `Migrator` (54 migrations)
+- `../migration/src/lib.rs` — `Migrator`
 
 ## Critical Gotchas
 
@@ -132,6 +132,8 @@ Custom key-value attributes on users, governed by a schema-first attribute defin
 
 **Value types**: `"string"` (→ Utf8 literal), `"integer"` (→ Int64), `"boolean"` (→ Boolean), `"list"` (→ list of strings, max 100 elements). Type-safe substitution in both template variables and decision function context. List attributes expand into multiple comma-separated string literals in `mangle_vars()` for use with `IN` clauses: `department IN ({user.departments})`. Empty lists expand to a NULL sentinel (effectively false). `parse_attributes()` returns `HashMap<String, serde_json::Value>` (not `HashMap<String, String>`).
 
+**Namespace design**: Attributes are nested under `attributes` in the API (`PUT /users/{id}` payload and response) but flat in expressions (`{user.KEY}`) and decision context (`ctx.session.user.KEY`). This is intentional — API nesting separates user-defined from built-in fields; expression flattening keeps policy authoring concise. Reserved key validation prevents collisions. See `docs/permission-system.md` § "Namespace design" for the full rationale.
+
 **Template variables**: `{user.KEY}` in filter/mask expressions. Built-in fields (`{user.tenant}`, `{user.username}`, `{user.id}`) take priority via `match` arms in `UserVars::get()`, preventing attribute override attacks. Custom attributes fall through to the attribute map.
 
 **Decision function context**: Custom attributes are flattened as first-class fields on `ctx.session.user` (e.g., `ctx.session.user.region`) with typed JSON values. Built-in fields (`id`, `username`, `tenant`, `roles`) always take priority. `ctx.session.time.now` is an ISO 8601 / RFC 3339 timestamp of the evaluation time (not session start).