Harden Little Bull Premium workspace controls

.gitignore

@@ -87,3 +87,7 @@ CLAUDE.md
 
 # Google Jules
 .jules/
+
+# Playwright local artifacts
+/lightrag_webui/test-results/
+/lightrag_webui/playwright-report/

CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## Unreleased
+
+- Added Little Bull premium control-plane contracts and PostgreSQL schema.
+- Added local tri-database pilot path for Postgres, Neo4j, and Qdrant.
+- Added non-destructive Phase 3 data-plane pilot harness and validation tests.

docs/cli-reference.md

@@ -0,0 +1,18 @@
+# CLI Reference
+
+## Project Commands
+
+- `python -m lightrag_enterprise.system.migrate`
+- `uv run ruff check lightrag_enterprise tests_enterprise lightrag/api/lightrag_server.py`
+- `./scripts/test.sh tests_enterprise -q`
+- `node /Users/joao_tourinho/Documents/specops-tooling-os/packages/cli/dist/index.js validate`
+
+## Pilot Commands
+
+- `scripts/little_bull_phase3_pilot.py` runs opt-in data-plane pilots.
+- `scripts/little_bull_phase3_inventory.py` lists pilot artifacts without deletion.
+
+## Acceptance Criteria
+
+- CLI commands do not echo secrets.
+- Destructive commands are not run without explicit confirmation.

docs/github-integration.md

@@ -0,0 +1,16 @@
+# GitHub Integration
+
+## Policy
+
+Pull requests should target `HKUDS/LightRAG:main` when publishing upstream work, from a dedicated branch.
+
+## Checks
+
+- Include summary, operational impact, linked issues, and validation evidence.
+- Use authenticated GitHub tooling only when credentials are valid.
+- Do not expose secrets in PR text, logs, screenshots, or artifacts.
+
+## Acceptance Criteria
+
+- PRs include test evidence for touched surfaces.
+- Upstream attribution and fork policy are preserved.

docs/installation.md

@@ -0,0 +1,17 @@
+# Installation
+
+## Local Setup
+
+Use the repository setup flow and keep secrets in local environment files that are not committed.
+
+## Commands
+
+- `python -m venv .venv && source .venv/bin/activate`
+- `pip install -e .`
+- `pip install -e .[api]`
+- `cd lightrag_webui && bun install`
+
+## Acceptance Criteria
+
+- Dependencies install without committing generated environments.
+- `.env` values remain local and are never printed in shared logs.

docs/little-bull-diagnostic-artifacts-inventory.md

@@ -0,0 +1,106 @@
+# Little Bull Diagnostic Artifacts Inventory
+
+Status date: 2026-05-01
+
+This inventory is read-only documentation for possible future cleanup. No cleanup has been executed.
+It contains no secrets, tokens, passwords, `.env` values or connection strings.
+
+## Rule
+
+Do not delete, drop, truncate, reset, prune, or remove any item in this file without explicit confirmation that names the exact targets.
+
+## Local Services Observed
+
+- `trag-phase2-postgres-1`: healthy, loopback Postgres service.
+- `trag-phase2-neo4j-1`: healthy, loopback Neo4j service.
+- `trag-phase2-qdrant-1`: healthy, loopback Qdrant service.
+
+These containers are diagnostic. Stopping them without volume deletion is lower risk than removing containers or volumes, but still should be coordinated if active tests depend on them.
+
+## Filesystem Artifacts
+
+Candidate directories under `rag_storage/`:
+
+- `rag_storage/phase21_smoke_18311564788c`: empty directory observed.
+- `rag_storage/phase21_smoke_820a9f72e3b4`: 10 files observed.
+- `rag_storage/reindex_smoke_933a0228`: empty directory observed.
+- `rag_storage/reindex_smoke_ac241841`: empty directory observed.
+
+Candidate directories under `inputs/`:
+
+- `inputs/phase21_smoke_18311564788c`
+- `inputs/phase21_smoke_820a9f72e3b4`
+- `inputs/phase21_smoke_820a9f72e3b4/__enqueued__`
+- `inputs/phase21_tribank_44657da3ed86`
+- `inputs/phase21_tribank_44657da3ed86/__enqueued__`
+- `inputs/reindex_smoke_933a0228`
+- `inputs/reindex_smoke_ac241841`
+
+Known document in `rag_storage/phase21_smoke_820a9f72e3b4`:
+
+- `doc-1588f7b35aed62f7a69230c53c9b711a`
+
+Visual smoke screenshots are temporary and may or may not exist depending on `/tmp` retention:
+
+- `/tmp/trag-little-bull-premium-mobile.png`
+- `/tmp/trag-little-bull-premium-tablet.png`
+- `/tmp/trag-little-bull-premium-desktop.png`
+
+## Qdrant Artifacts
+
+Collections observed on the local diagnostic Qdrant service:
+
+- `lightrag_vdb_chunks_openai_text_embedding_3_small_1536d`
+- `lightrag_vdb_entities_openai_text_embedding_3_small_1536d`
+- `lightrag_vdb_relationships_openai_text_embedding_3_small_1536d`
+- `lightrag_vdb_chunks_phase3_fake_local_phase3_pilot_20260430130751_16d`
+- `lightrag_vdb_entities_phase3_fake_local_phase3_pilot_20260430130751_16d`
+- `lightrag_vdb_relationships_phase3_fake_local_phase3_pilot_20260430130751_16d`
+- `lightrag_vdb_chunks_phase3_fake_local_phase3_pilot_20260430130805_16d`
+- `lightrag_vdb_entities_phase3_fake_local_phase3_pilot_20260430130805_16d`
+- `lightrag_vdb_relationships_phase3_fake_local_phase3_pilot_20260430130805_16d`
+- `lightrag_vdb_chunks_phase3_fake_local_phase3_pilot_20260430130847_16d`
+- `lightrag_vdb_entities_phase3_fake_local_phase3_pilot_20260430130847_16d`
+- `lightrag_vdb_relationships_phase3_fake_local_phase3_pilot_20260430130847_16d`
+
+Workspace-specific counts observed for `phase21_tribank_44657da3ed86`:
+
+- `lightrag_vdb_chunks_openai_text_embedding_3_small_1536d`: 1 point with `workspace_id=phase21_tribank_44657da3ed86`.
+- `lightrag_vdb_entities_openai_text_embedding_3_small_1536d`: 5 points with `workspace_id=phase21_tribank_44657da3ed86`.
+- `lightrag_vdb_relationships_openai_text_embedding_3_small_1536d`: 0 points with `workspace_id=phase21_tribank_44657da3ed86`.
+
+Do not delete whole shared OpenAI collections just to remove one workspace. A future cleanup should use workspace-filtered point deletion only after explicit approval.
+
+## Neo4j Artifacts
+
+Indexes observed in the local diagnostic Neo4j service:
+
+- `entity_id_fulltext_idx_phase21_smoke_18311564788c`
+- `entity_id_fulltext_idx_phase21_smoke_820a9f72e3b4`
+- `entity_id_fulltext_idx_phase21_tribank_44657da3ed86`
+
+Workspace-property counts for `phase21_tribank_44657da3ed86` returned 0 nodes and 0 relationships. The index remains a cleanup candidate.
+
+## PostgreSQL / Control Plane Artifacts
+
+Known diagnostic workspaces/documents created during live smokes:
+
+- workspace `phase21_smoke_820a9f72e3b4`
+  - document `doc-1588f7b35aed62f7a69230c53c9b711a`
+- workspace `phase21_tribank_44657da3ed86`
+  - document `doc-974a377549c90fa3d2434ec663c8b1f4`
+
+PostgreSQL cleanup must be planned from table metadata and foreign-key order before any `DELETE`, `DROP`, or `TRUNCATE`.
+Prefer a read-only SQL inventory first, then a dry-run transaction script that rolls back, then an approved cleanup transaction.
+
+## Safe Next Step For Cleanup
+
+If cleanup is approved later, first generate a read-only cleanup packet containing:
+
+- exact filesystem paths;
+- exact Qdrant collection names and workspace-filter predicates;
+- exact Neo4j index names and any node/relationship predicates;
+- exact PostgreSQL tables and row counts by workspace/document id;
+- rollback notes or rebuild path for each plane.
+
+No destructive command should be run before that packet is reviewed and approved.

docs/little-bull-phase21-pr-notes.md

@@ -0,0 +1,79 @@
+# Little Bull Premium Phase 21 PR Notes
+
+Status date: 2026-05-01
+
+This note summarizes commit `40779b98 Fix Little Bull permissions and tri-bank smoke`.
+It contains no secrets, tokens, passwords, `.env` values or connection strings.
+
+## Summary
+
+- Hardened Little Bull Premium document upload so classified uploads require group and subgroup selection.
+- Added typed frontend API contracts for knowledge groups, subgroups and classified document upload responses.
+- Added pure workspace helpers for Premium navigation permissions, upload readiness, subgroup filtering and stale selection cleanup.
+- Added Bun coverage for classified upload, permission fallbacks and frontend API upload parameters.
+- Added Playwright visual smoke coverage for the Premium shell across mobile, tablet and desktop viewports.
+- Fixed macOS Bash 3.2 drift by making direct setup execution and interactive setup tests prefer Bash 4+ when available.
+- Closed least-privilege UI permission bugs: document listing works with `little_bull.documents.read`, scoped workspace choices can be derived from the principal, and taxonomy for classified upload remains gated by `little_bull.areas.read`.
+- Recorded additive live-smoke and strict tri-bank smoke evidence in the Little Bull risk register.
+
+## Backend / Control Plane
+
+- Little Bull service/router/models/admin store were extended for the Phase 20/21 hardening path already covered by enterprise contract tests.
+- Classified upload contracts now preserve workspace, group, subgroup and registry document identifiers through backend/frontend boundaries.
+- No global `NEO4J_WORKSPACE`, `QDRANT_WORKSPACE` or `POSTGRES_WORKSPACE` override was set.
+- No Neo4j/Qdrant data was deleted or reset.
+
+## Frontend
+
+- `LittleBullPreview` now loads groups/subgroups for uploads and blocks file selection until classification is complete.
+- Document refresh no longer fails for users who can read documents but cannot read areas.
+- Users without area-listing permission can still select scoped workspaces from their principal `workspace_ids`.
+- `littleBullWorkspace.ts` centralizes permission and upload state rules for direct unit testing.
+- Playwright smoke uses route-mocked local API responses and a fake non-secret JWT.
+- Playwright reports and test-results are ignored by git.
+
+## Validation Evidence
+
+- `uv run ruff check lightrag_enterprise tests_enterprise lightrag/api/lightrag_server.py tests/test_interactive_setup/_helpers.py`
+- `python -m lightrag_enterprise.system.migrate`
+- `./scripts/test.sh tests_enterprise -q`: 184 passed, 4 skipped.
+- `./scripts/test.sh tests -q`: 794 passed, 32 skipped.
+- `cd lightrag_webui && bun test`: 21 passed.
+- `cd lightrag_webui && bunx tsc --noEmit`
+- `cd lightrag_webui && bun run lint`
+- `cd lightrag_webui && bun run test:visual`: 3 passed.
+- `cd lightrag_webui && bun run build`
+- `node /Users/joao_tourinho/Documents/specops-tooling-os/packages/cli/dist/index.js validate`: 0 issues.
+- `node /Users/joao_tourinho/Documents/specops-tooling-os/packages/cli/dist/index.js eval`: 10 passed, 0 failed.
+- `git diff --check`
+
+## Smoke Evidence
+
+- Additive current-worktree smoke on temporary server `127.0.0.1:9631`:
+  - workspace `phase21_smoke_820a9f72e3b4`
+  - document `doc-1588f7b35aed62f7a69230c53c9b711a`
+  - naive query returned 1 retrieval reference
+  - server stopped after validation
+
+- Strict tri-bank smoke on temporary server `127.0.0.1:9632`:
+  - target storage: PGKV/PGDocStatus + Neo4j + Qdrant
+  - workspace `phase21_tribank_44657da3ed86`
+  - document `doc-974a377549c90fa3d2434ec663c8b1f4`
+  - Qdrant counts for this workspace: 1 chunk, 5 entities, 0 relationships
+  - naive query returned 1 retrieval reference
+  - server stopped after validation
+
+## Rollback
+
+- Disable feature flags when applicable:
+  - `LITTLE_BULL_GRAPH_V2_ENABLED`
+  - `LITTLE_BULL_QDRANT_DATA_PLANE_ENABLED`
+  - `LITTLE_BULL_OBSIDIAN_WORKSPACE_ENABLED`
+- PostgreSQL remains the control-plane source of truth.
+- Neo4j and Qdrant artifacts are rebuildable from control-plane state plus reindexing.
+- Do not run cleanup commands without explicit approval and exact target list.
+
+## READY Status
+
+Do not declare READY from this note alone.
+READY still requires final release review, explicit cleanup decision if cleanup is desired, and all production release gates.