@terreno/mcp 0.25.0 → 0.27.0

package/src/docs/versioned/0.26.0/tasks/admin-ui-v2-django-parity.md

@@ -0,0 +1,135 @@
+# Task List: Admin UI v2 — Django-Parity Admin (Config-Driven Shell)
+
+*Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
+
+**Status:** All phases below are complete. See `docs/implementationPlans/admin-ui-v2-django-parity.md` for acceptance criteria (also marked complete) and verification pointers.
+
+**Companion:** **Admin script runner** — `docs/implementationPlans/admin-script-runner.md` + `docs/tasks/admin-script-runner.md` (same delivery; documents `/admin/scripts/*`, `BackgroundTask`, and UI).
+
+See: `docs/implementationPlans/admin-ui-v2-django-parity.md` for full plan.
+
+## Phase 1: Admin config contract (backend)
+
+- [x] **Task 1.1**: Extend `AdminConfigResponse` / `GET /admin/config` for schema v2  
+  - Description: Add `schemaVersion`, per-model `group`, `listDisplay`, `listDisplayLinks`, `sortableFields`, `searchFields`, `filters` (typed: boolean, choice, text, dateRange, ref), `fieldsets`, `readonlyFields`, `hiddenFields`, declared `actions` (sync vs `background: true`), `permissions` (`create`/`update`/`delete` booleans), `pageSize`, `realtime`, `home` with **`title` + `slots`** (`navGlobal?`, `contentTop?`, `main?`, `sidebar?` — each an ordered `string[]` of widget ids; Django template-block analogue). Optionally accept legacy `home.widgets[]` for migration → normalize into `slots.main` + `recentActivity` forced last in `sidebar`. Include `customScreens`, existing `scripts`. Preserve v1 config fields for backward compatibility.  
+  - Files: `admin-backend/src/adminApp.ts`, `admin-backend/src/index.ts` (exports if needed), tests under `admin-backend/src/*.test.ts`  
+  - Depends on: none  
+  - Acceptance: Typed response; tests assert v1 fields still present; new fields optional-safe for old clients.
+
+- [x] **Task 1.2**: Document OpenAPI for extended config  
+  - Description: Ensure generated OpenAPI documents the new response shape (or manual `openApiBuilder` attachment on config route if required).  
+  - Files: `admin-backend/src/adminApp.ts`  
+  - Depends on: 1.1  
+  - Acceptance: `openapi.json` from a test server includes `/admin/config` response schema additions.
+
+## Phase 2: Bulk patch + background tasks (backend)
+
+- [x] **Task 2.1**: Implement `POST {basePath}{routePath}/bulk-patch`  
+  - Description: Body `{ ids: string[]; patch: Record<string, unknown> }`. Enforce **max 1000** ids. Allowlist patch keys per model from config (or from schema paths). Use `updateMany` / batched updates with per-id validation where needed. Return `{ updated: number; failures?: ... }`.  
+  - Files: `admin-backend/src/adminApp.ts`, new helper module if >300 LOC, tests  
+  - Depends on: 1.1  
+  - Acceptance: Tests for cap, unknown keys rejected, partial failure reporting; `IsAdmin` only.
+
+- [x] **Task 2.2**: Implement `POST /admin/background-tasks` (name finalized in code)  
+  - Description: Map prototype `background: true` actions to enqueue `BackgroundTask` (or existing script runner) with `kind`, target route, ids, metadata. Return `{ taskId }`. Reuse logging/error patterns from script routes.  
+  - Files: `admin-backend/src/adminApp.ts`, tests  
+  - Depends on: 1.1, 2.1 (shared validation helpers optional)  
+  - Acceptance: Test covers enqueue + 403 non-admin; OpenAPI entry exists.
+
+## Phase 3: modelRouter metadata parity (backend / examples)
+
+- [x] **Task 3.1**: Align `modelRouter` registration options with config lists  
+  - Description: For each model exposed in `example-backend` (or chosen demo), set `queryFields`, `sort`, `defaultLimit`/`maxLimit`, `responseHandler` for hidden fields, and `permissions.delete: []` for DotPhrase-style demo.  
+  - Files: `example-backend/src/**`, any consumer `AdminApp` registration  
+  - Depends on: 1.1  
+  - Acceptance: List queries accept filters used in UI; delete disabled where specified.
+
+## Phase 4: Admin frontend — shell + navigation
+
+- [x] **Task 4.1**: Admin shell (sidebar groups, screens, tools, user footer)  
+  - Description: New layout components using `@terreno/ui`; consume config for groups and `customScreens`; support `apiBase`/`routeBase` from prior admin-spa work.  
+  - Files: `admin-frontend/src/**` (new shell module + exports in `index.tsx`)  
+  - Depends on: 1.1  
+  - Acceptance: Lint/compile; story or test renders grouped nav from mock config.
+
+- [x] **Task 4.2**: Top bar breadcrumbs + contextual actions  
+  - Description: Match prototype routes (home, list, form, tool, screen); “Add {singular}” when `permissions.create !== false`.  
+  - Files: `admin-frontend/src/**`  
+  - Depends on: 4.1  
+  - Acceptance: Unit test for breadcrumb labels from route + model meta.
+
+## Phase 5: Admin frontend — list (changelist)
+
+- [x] **Task 5.1**: List view v2 — search, filters, sort, pagination  
+  - Description: Wire `DataTable` to server sort/page; debounced search; typed filters mapped to query params; `listDisplayLinks` drives link columns; inline boolean uses PATCH.  
+  - Files: `admin-frontend/src/AdminModelTable.tsx`, hooks, types  
+  - Depends on: 1.1, 3.1, 4.1  
+  - Acceptance: Tests with MSW or harness for query serialization; loading/error/empty states.
+
+- [x] **Task 5.2**: Bulk selection + action menu  
+  - Description: Sync actions call `bulk-patch`; confirm modals for `confirm` strings; background actions call enqueue endpoint; cap selection client-side at 1000 with user-visible message.  
+  - Files: `admin-frontend/src/AdminModelTable.tsx`, possibly `AdminScriptRunModal.tsx` reuse  
+  - Depends on: 2.1, 2.2, 5.1  
+  - Acceptance: Tests for confirm + request bodies.
+
+## Phase 6: Admin frontend — form (change view)
+
+- [x] **Task 6.1**: Fieldsets + readonly + exclude/hidden fields  
+  - Description: Render `fieldsets` with `Accordion`/`Card`; readonly fields not submitted; hidden fields omitted from form and detail panels as specified.  
+  - Files: `admin-frontend/src/AdminModelForm.tsx`, types  
+  - Depends on: 1.1, 4.1  
+  - Acceptance: Test that PATCH body excludes readonly keys.
+
+- [x] **Task 6.2**: Autocomplete ref picker  
+  - Description: Debounced fetch against referenced model list endpoint; keyboard/accessibility basics.  
+  - Files: `admin-frontend/src/AdminRefField.tsx` or new component, tests  
+  - Depends on: 5.1 (shared debounce util optional)  
+  - Acceptance: Unit test uses mock list API.
+
+## Phase 7: Home dashboard widgets
+
+- [x] **Task 7.1**: Widget registry + **`home.slots`** layout  
+  - Description: Implement built-ins: `modelStats`, `modelsGrid`, `feature-flags-overrides` (or generic “quick toggles” plugin slot), `versionConfig` summary, `scriptRunner`, `recentActivity`. Render regions in order: **`navGlobal`** (horizontal strip) → **`contentTop`** (full-width above grid) → **`main` | `sidebar`** (two-column). Enforce **`recentActivity` last within `sidebar`** when present. Validate unknown widget ids in dev.  
+  - Files: `admin-frontend/src/**` (new `AdminHome.tsx` or similar), exports  
+  - Depends on: 1.1, 4.1  
+  - Acceptance: Tests: (1) `scriptRunner` only in `navGlobal` does not mount inside `main` model grid; (2) `recentActivity` is last in `sidebar` when configured.
+
+## Phase 8: admin-spa + example integration
+
+- [x] **Task 8.1**: Wire new shell + routes in `admin-spa`  
+  - Description: Routes for home v2, list, form, tools, deep links to plugin URLs for screens; regenerate admin SDK if needed.  
+  - Files: `admin-spa/app/**`, `admin-spa/store/**`  
+  - Depends on: 4.x–7.x  
+  - Acceptance: `bun run admin-spa:compile` / smoke script; manual checklist in plan.
+
+- [x] **Task 8.2**: Example-backend registration + seed  
+  - Description: Register illustrative models + `AdminApp` config entries matching v2 demo shape (subset acceptable).  
+  - Files: `example-backend/**`  
+  - Depends on: 3.1  
+  - Acceptance: Running example + admin-spa exercises list/form/home.
+
+## Phase 9 (last): Audit log + recent actions
+
+- [x] **Task 9.1**: `AdminAuditLog` model + persistence (consumer or example-backend)  
+  - Description: Schema with descriptions, indexes on `created`, `modelName`, `actorId`. Optional TTL for retention.  
+  - Files: `example-backend/src/models/**` (or consumer app), types  
+  - Depends on: 8.2 (demo path)  
+  - Acceptance: Model compiles; `checkModelsStrict` happy in non-prod.
+
+- [x] **Task 9.2**: `modelRouter` or read-only list route for audit entries  
+  - Description: `GET` list with pagination, `IsAdmin`, sort `-created`. Consider create-only via internal hooks (no public POST from browser) — prefer server-side logging middleware writing entries.  
+  - Files: `example-backend/src/api/**`, tests  
+  - Depends on: 9.1  
+  - Acceptance: supertest list route returns inserted fixture rows.
+
+- [x] **Task 9.3**: Emit audit rows from admin mutations  
+  - Description: Hook `postUpdate`/`postCreate`/`postDelete` on registered admin models or central middleware in `AdminApp` to write `AdminAuditLog` with verb + label resolution.  
+  - Files: `admin-backend/src/adminApp.ts` and/or example-backend hooks  
+  - Depends on: 9.2  
+  - Acceptance: `onAdminAudit` fires after POST/PATCH/DELETE on admin model routes — **`admin-backend/src/adminApp.models.test.ts`** (`describe("AdminApp onAdminAudit")`). Consumer persistence: `example-backend/src/server.ts` (`AdminAuditLog.create` in `onAdminAudit`).
+
+- [x] **Task 9.4**: Home `recentActivity` widget backed by API  
+  - Description: Fetch latest N audit rows; render as the **final widget in `home.slots.sidebar`**; empty/error states.  
+  - Files: `admin-frontend/src/**` (home widget), `useAdminApi` or dedicated hook  
+  - Depends on: 7.1, 9.3  
+  - Acceptance: UI or integration test shows `recentActivity` below other **sidebar** widgets when multiple sidebar ids are configured.

package/src/docs/versioned/0.26.0/tasks/syncdb-local-first.md

@@ -0,0 +1,117 @@
+# Task List: SyncDB Local-First Data Layer
+
+*Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
+
+## Phase 1: Foundation
+
+- [ ] **Task 1.1**: Scaffold `@terreno/syncdb` package
+  - Description: Create the package with core entrypoints, lifecycle interfaces, and typed configuration.
+  - Files: `syncdb/package.json` (new), `syncdb/src/index.ts` (new), `syncdb/src/types.ts` (new), `syncdb/README.md` (new)
+  - Depends on: none
+  - Acceptance: package compiles and exports `createSyncDbClient` and configuration types.
+
+- [ ] **Task 1.2**: Define storage and sync contracts
+  - Description: Add canonical interfaces for entities, outbox records, sync cursors, conflicts, and keyring entries.
+  - Files: `syncdb/src/storage/types.ts` (new), `syncdb/src/sync/types.ts` (new), `syncdb/src/crypto/types.ts` (new)
+  - Depends on: Task 1.1
+  - Acceptance: type checks enforce required fields and operations.
+
+## Phase 2: Local DB and Encryption
+
+- [ ] **Task 2.1**: Implement IndexedDB adapter with migrations
+  - Description: Add object stores for entities/outbox/cursors/conflicts/keyring and schema version migration support.
+  - Files: `syncdb/src/storage/indexedDb.ts` (new), `syncdb/src/storage/migrations.ts` (new), `syncdb/src/storage/indexedDb.test.ts` (new)
+  - Depends on: Task 1.2
+  - Acceptance: storage CRUD + migration tests pass.
+
+- [ ] **Task 2.2**: Implement key manager (Web Crypto)
+  - Description: Add DEK generation + wrap/unwrap logic and persistence integration.
+  - Files: `syncdb/src/crypto/keyManager.ts` (new), `syncdb/src/crypto/keyManager.test.ts` (new)
+  - Depends on: Task 1.2
+  - Acceptance: key lifecycle tests pass for generate/wrap/unwrap/reload.
+
+- [ ] **Task 2.3**: Encrypt IndexedDB payloads at rest
+  - Description: Add AES-GCM envelope encryption/decryption and integrate in storage read/write paths.
+  - Files: `syncdb/src/crypto/envelope.ts` (new), `syncdb/src/storage/secureStorage.ts` (new), `syncdb/src/crypto/envelope.test.ts` (new)
+  - Depends on: Task 2.1, Task 2.2
+  - Acceptance: tests verify no plaintext persistence and successful decrypt roundtrip.
+
+## Phase 3: Local Mutation Engine
+
+- [ ] **Task 3.1**: Add optimistic local mutation application
+  - Description: Apply local patches immediately and retain inverse patches for rollback.
+  - Files: `syncdb/src/mutations/optimistic.ts` (new), `syncdb/src/mutations/optimistic.test.ts` (new)
+  - Depends on: Task 2.3
+  - Acceptance: immediate local apply and rollback tests pass.
+
+- [ ] **Task 3.2**: Implement durable outbox state machine
+  - Description: Persist queued mutations and manage transitions `queued -> inFlight -> acked/conflicted/failed`.
+  - Files: `syncdb/src/mutations/outbox.ts` (new), `syncdb/src/mutations/outbox.test.ts` (new)
+  - Depends on: Task 3.1
+  - Acceptance: replay transition and retry logic tests pass.
+
+- [ ] **Task 3.3**: Implement conflict capture and resolution
+  - Description: Persist conflict records and support `useServer` and `keepMine` resolution paths.
+  - Files: `syncdb/src/mutations/conflicts.ts` (new), `syncdb/src/mutations/conflicts.test.ts` (new)
+  - Depends on: Task 3.2
+  - Acceptance: both resolution strategies correctly update local state and queue state.
+
+## Phase 4: Websocket Delta Sync
+
+- [ ] **Task 4.1**: Build sync transport client
+  - Description: Add websocket connect/auth/reconnect lifecycle and sync event channel handling.
+  - Files: `syncdb/src/sync/transport.ts` (new), `syncdb/src/sync/transport.test.ts` (new)
+  - Depends on: Task 1.2
+  - Acceptance: transport lifecycle tests pass including reconnect behavior.
+
+- [ ] **Task 4.2**: Implement cursor-aware delta applier
+  - Description: Apply deltas idempotently with monotonic cursor checks and gap handling.
+  - Files: `syncdb/src/sync/deltaApplier.ts` (new), `syncdb/src/sync/deltaApplier.test.ts` (new)
+  - Depends on: Task 2.3, Task 4.1
+  - Acceptance: ordered delta tests pass; duplicate/out-of-order deltas are safely handled.
+
+- [ ] **Task 4.3**: Wire ack/nack replay coordinator
+  - Description: Connect outbox replay to server ack/nack responses and conflict creation.
+  - Files: `syncdb/src/sync/replayCoordinator.ts` (new), `syncdb/src/sync/replayCoordinator.test.ts` (new)
+  - Depends on: Task 3.3, Task 4.2
+  - Acceptance: ack finalizes queued mutations; nack creates conflict records.
+
+## Phase 5: App Integration and Migration Bridge
+
+- [ ] **Task 5.1**: Implement React hooks and provider
+  - Description: Add `useEntity`, `useQuery`, `useMutation`, `useSyncStatus`, and context provider wiring.
+  - Files: `syncdb/src/react/provider.tsx` (new), `syncdb/src/react/hooks.ts` (new), `syncdb/src/react/hooks.test.tsx` (new)
+  - Depends on: Task 3.3, Task 4.3
+  - Acceptance: hooks update on local mutations and remote deltas.
+
+- [ ] **Task 5.2**: Add Redux migration bridge
+  - Description: Provide optional adapter for Redux-based consumers transitioning from `@terreno/rtk`.
+  - Files: `syncdb/src/bridge/reduxBridge.ts` (new), `syncdb/src/bridge/reduxBridge.test.ts` (new)
+  - Depends on: Task 5.1
+  - Acceptance: bridge supports selector and dispatch-driven mutation usage.
+
+- [ ] **Task 5.3**: Integrate `example-frontend` todos behind `USE_SYNCDB`
+  - Description: Switch todos flow to syncdb under a feature flag while keeping legacy path available.
+  - Files: `example-frontend/store/index.ts`, `example-frontend/store/sdk.ts`, `example-frontend/app/(tabs)/index.tsx`, `example-frontend/app/_layout.tsx`
+  - Depends on: Task 5.1, Task 5.2
+  - Acceptance: flagged path supports offline local create/update/delete and sync reconciliation.
+
+## Phase 6: Codegen and Validation
+
+- [ ] **Task 6.1**: Prototype `@terreno/syncdb-codegen`
+  - Description: Create codegen package that emits typed syncdb operation descriptors from OpenAPI.
+  - Files: `syncdb-codegen/package.json` (new), `syncdb-codegen/src/index.ts` (new), `syncdb-codegen/src/*.test.ts` (new)
+  - Depends on: Task 1.1
+  - Acceptance: generator produces valid descriptors for one sample domain.
+
+- [ ] **Task 6.2**: Author migration docs
+  - Description: Document migration path from `@terreno/rtk` to `@terreno/syncdb` and rollout strategy.
+  - Files: `syncdb/README.md`, `docs/implementationPlans/syncdb-local-first.md`
+  - Depends on: Task 5.3
+  - Acceptance: docs include setup, API usage, and feature-flag rollout playbook.
+
+- [ ] **Task 6.3**: Run validation suite
+  - Description: Execute compile, lint, and tests for touched packages and resolve regressions.
+  - Files: as needed in touched packages
+  - Depends on: Task 6.2
+  - Acceptance: relevant compile/lint/test commands pass with no blockers.

package/src/docs/versioned/next/explanation/README.md

@@ -11,3 +11,4 @@ Understanding-oriented documentation: concepts, architecture, and context.
 - [GCP hosting architecture](gcp-hosting-architecture.md) — Static site hosting with GCS and Cloud CDN
 - [Modular API design](modular-api-design.md) — 🚧 Why TerrenoApp replaces setupServer
 - [modelRouter actions](model-router-actions.md) — Named collection and instance operations on modelRouter
+- [No barrel imports](no-barrel-imports.md) — Import concrete modules, not `index` re-export barrels

package/src/docs/versioned/next/explanation/explicit-any-policy.md

@@ -0,0 +1,88 @@
+# Explicit `any` policy
+
+Terreno discourages `any` in TypeScript. Biome blocks **new** unsuppressed explicit `any` at lint time; this document describes how we inventory existing usages and track remediation.
+
+## Why
+
+- **Type safety**: `any` disables checking and hides bugs at compile time.
+- **Refactor confidence**: precise types make API and UI changes safer.
+- **Consistency**: one convention for when `any` is acceptable and how it is documented.
+
+Prefer `unknown` (and narrow) or a precise type. Use `as unknown as T` over `as any as T` when a cast is unavoidable.
+
+## Allowed uses
+
+Explicit `any` is acceptable only at **framework or library boundaries** where types are not expressible in TypeScript today, for example:
+
+- Mongoose `Schema<any, …>` accepting arbitrary consumer schemas (`api/src/plugins.ts`)
+- RTK Query `Api<any, any, any, any>` in generic middleware (`rtk/src/offlineMiddleware.ts`)
+- Dynamic RTK hook lookup where endpoint names are not statically known (`admin-frontend`)
+- Test mocks with type-erased doubles (`*.test.ts`, `*.isolated.tsx`)
+
+Every allowed use must be **lint-clean** and **documented** (see below).
+
+## Remediation status
+
+The audit script (`bun run check:explicit-any`) classifies each explicit `any`:
+
+| Status | Meaning |
+|--------|---------|
+| `violation` | No `biome-ignore` — fails Biome lint |
+| `suppressed-only` | Has `biome-ignore` but missing `// noExplicitAny:` rationale |
+| `fully-documented` | Has both `biome-ignore` and `// noExplicitAny:` |
+| `file-blanket` | File-level `biome-ignore-all` without file-level `noExplicitAny:` |
+| `out-of-scope` | In Biome-excluded source (e.g. `api/src/populate.ts`) |
+
+## How to document an `any`
+
+When `any` cannot be removed, add **both** comments on the line above (or a file header for tests):
+
+```typescript
+// noExplicitAny: RTK Query generates hook names dynamically; not statically expressible
+// biome-ignore lint/suspicious/noExplicitAny: dynamic hook lookup on RTK Query enhanced API
+const hook = (api as any)[`useGet${name}Query`];
+```
+
+For test files with many mocks, a file-level header is fine:
+
+```typescript
+// noExplicitAny: test mocks use type-erased RTK Query API doubles
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
+```
+
+## Commands
+
+```bash
+bun run check:explicit-any                         # summary report
+bun run check:explicit-any:json                    # JSON inventory
+bun run check:explicit-any:baseline                # fail if counts regress vs baseline
+bun run check:explicit-any -- --undocumented       # only suppressed-but-undocumented
+bun run check:explicit-any -- --list --undocumented  # file:line list for remediation
+bun run check:explicit-any -- --production-only --undocumented --list
+bun run check:explicit-any -- --package=api        # filter to one package
+bun run check:explicit-any -- --include-excluded   # include Biome-excluded files
+bun run check:explicit-any -- --write-baseline     # refresh scripts/check-explicit-any/baseline.json
+bun run check:explicit-any:remediate               # auto-add missing noExplicitAny: comments
+```
+
+## Enforcement
+
+| Layer | What it does |
+|-------|----------------|
+| **Biome `noExplicitAny: error`** | Blocks new unsuppressed `any` in every linted package |
+| **`bun run check:explicit-any:baseline`** | CI ratchet — total, undocumented, and violation counts must not increase |
+| **`bun run lint`** | Per-package lint including `noExplicitAny` |
+
+Baseline file: `scripts/check-explicit-any/baseline.json`. After intentional reductions (removing or properly documenting `any`), refresh with `--write-baseline` and commit the updated baseline.
+
+## Remediation workflow
+
+1. Run `bun run check:explicit-any -- --list --undocumented --production-only` for a work queue.
+2. For each hit, either **replace** `any` with a proper type or **document** with `noExplicitAny:` + `biome-ignore`.
+3. Prefer line-level suppressions over file-level `biome-ignore-all` in production code.
+4. Run `bun run check:explicit-any:baseline` before opening a PR.
+5. If counts decreased, run `--write-baseline` and commit the new baseline.
+
+## Exclusions
+
+The audit skips generated and template files (`openApiSdk.ts`, `*.template.ts`). Biome-excluded paths (see `!!` patterns in `biome.jsonc`) are omitted unless `--include-excluded` is passed.

package/src/docs/versioned/next/explanation/no-barrel-imports.md

@@ -0,0 +1,49 @@
+# No barrel imports
+
+Terreno avoids **barrel imports** — imports that resolve through an `index.ts` / `index.tsx` file that only re-exports other modules.
+
+## Why
+
+- **Clearer dependencies**: each import names the file that defines the symbol.
+- **Faster tooling**: bundlers and TypeScript do less re-export chasing.
+- **Fewer cycles**: internal barrels (especially package `index` files) are a common source of circular dependencies.
+
+## Allowed
+
+- **Published package APIs** — cross-package imports like `@terreno/api`, `@terreno/ui`, and `@terreno/rtk` use each package's public `src/index` entry. That is intentional.
+- **Package public entry files** — `api/src/index.ts`, `ui/src/index.tsx`, etc. may re-export for npm consumers. Do not import those barrels from *inside* the same package.
+- **Expo Router routes** — `app/**/index.tsx` files are route entries, not barrels.
+
+## Not allowed
+
+Internal barrel `index` files do not exist in this repo — the Biome `noBarrelFile` override bans creating them, so a directory import like `../models` has nothing to resolve to and fails to compile.
+
+Importing a directory that resolves to a re-exporting index file:
+
+```typescript
+// Bad — resolves to models/index.ts
+import {User} from "../models";
+
+// Good — imports the defining module
+import {User} from "../models/user";
+```
+
+```typescript
+// Bad — store/index.ts was a barrel of sdk/appState/utils
+import {useGetMeQuery} from "@/store";
+
+// Good
+import {useGetMeQuery} from "@/store/sdk";
+import store, {useAppDispatch} from "@/store/index";
+```
+
+## Enforcement
+
+No generation step is required — internal barrel `index` files are banned outright, so there is never a list of barrels to keep in sync.
+
+- **Biome `noBarrelFile` override** (root `biome.jsonc`): bans internal barrel `index.ts` / `index.tsx` files during lint. Package public entries (`src/index.ts[x]`) and Expo Router routes (`app/**`) are exempt.
+- **Biome plugin**: `biome/plugins/no-barrel-imports.grit` — a small static GritQL plugin that flags path-alias directory imports (`@/store`, `@components`, …) in the packages that define those aliases (`example-frontend`, `admin-spa`, `demo`).
+- **CI**: `bun run check:no-barrel-imports` — resolution-based safety net that fails if any internal barrel index file exists or any import resolves through one (see root `package.json` → `terreno.policies.noBarrelImports`).
+- **AI rules**: `.rulesync/rules/00-root.md` and package `.ai/guidelines/core.md` files
+
+When scaffolding new code (MCP bootstrap, examples), always generate direct module paths — never `models/index`, `@/store`, or `@components` without a concrete file.

package/src/docs/versioned/next/implementationPlans/PLAN_INDEX.md

@@ -7,6 +7,7 @@ Tracks active and completed implementation plans (IP) for Terreno. File paths ar
 | Plan | Status | Created | Tasks |
 |------|--------|---------|-------|
 | [Admin UI v2 — Django-parity admin](admin-ui-v2-django-parity.md) | Approved | 2026-06-15 | [tasks](../tasks/admin-ui-v2-django-parity.md) |
+| [RBAC Permissions](rbac-permissions.md) | Draft (API design) | 2026-07-08 | TBD |
 
 ## Completed