The LQ.AI Atlas
LQ.AI's documentation, bound to the code it describes
Journeys
First hour with LQ.AI
The orientation path: what LQ.AI is and why, how to run it, how decisions are routed, the system shape, and how to tell what's real.
7 stops →The Inference Gateway: the security boundary
The component that holds the keys and guards the egress: its pipeline, the threat model around it, what anonymization does to outbound prompts, how model routing stays inspectable, and where the inference-tier boundary sits.
6 stops →Document review & citations, end to end
How a contract becomes reviewed, cited, and trustworthy: the verification cascade, where citations are stored, the playbook and tabular surfaces that ride on it, and the honest edges where verification stops.
5 stops →The Autonomous Layer (M4)
The opt-in background executor and the discipline that makes unattended agency acceptable: its design lineage, the five-phase walk, the single chokepoint, the brakes, the honest caveats, and what shipped.
6 stops →Getting Started
The front door. What LQ.AI is, how to stand it up, and the agent-orientation file that routes every implementation decision. Start with README, run it via QUICKSTART, then keep CLAUDE.md open as you work.
- LQ.AI Your very first stop in this repository.
- LQ.AI — Quickstart Walkthrough When you're actually standing the stack up and running your first skill.
- Master Services Agreement
- Master Services Agreement
- Master Services Agreement
- Master Services Agreement
- Master Services Agreement
- MUTUAL NON-DISCLOSURE AGREEMENT
- Mutual Non-Disclosure Agreement
- Mutual Non-Disclosure Agreement
- Mutual Non-Disclosure Agreement
- Mutual Non-Disclosure Agreement
- Mutual Non-Disclosure Agreement
- Orientation for Claude Code (and other coding assistants) Before your first contribution — for decision routing, code style, and the write-time pitfalls.
- Sample MSA corpus
- Sample NDA corpus
Product & Vision
The canonical specification and the live work list it generates. The PRD is the reference of record (transparency as a founding principle, the five-tier inference spectrum, the DE-XXX backlog); HONEST-STATE is its conscience — what actually ships today vs. what's plumbing — and ROADMAP turns the gap into sized, tagged contributor tasks.
- Honest State Whenever you need the truth about what works today vs. what's plumbing — with the file or test that proves it.
- LQ.AI Open Roadmap When you want to pick up open work sized and tagged to your background.
- LQ.AI — Product Requirements Document The reference of record for any product, capability, or architectural decision — jump to the relevant § via its table of contents.
Architecture & Decisions
Why the system is shaped this way: the self-hosted topology, the single gateway security boundary, the Postgres 16 + pgvector schema, the observability surface, the opt-in autonomous executor — and the 13 ADRs that record each load-bearing decision and the tradeoff it accepted.
- ADR 0001 — OpenWebUI fork pin and refresh strategy You're rebasing the OpenWebUI fork, adding web/ customizations, or reasoning about the branding obligations.
- ADR 0002 — Backend (FastAPI) owns authentication You're touching auth flows, session/JWT handling, or IdP integration.
- ADR 0003 — Error handling: parallel `lq_ai.errors` packages with an OpenAPI-defined contract You're raising or mapping errors across api/ and gateway/, or wondering why the two services use different envelope keys.
- ADR 0004 — Skill loader lives in the backend (`api/`), not the gateway You're working on skill loading/registry, prompt assembly, or wondering why skills have no SQL table.
- ADR 0005 — File-storage soft-delete and MinIO key scheme You're touching file upload/download/delete, the MinIO key layout, or the deletion/GC lifecycle.
- ADR 0006 — Document pipeline architecture You're working on document parsing/chunking, the ingest worker, or why embeddings are generated downstream.
- ADR 0007 — Skill prompt assembly: gateway↔backend auth, templating, and request surface You're touching gateway↔backend skill fetch, the {{var}} substitution, or skill provenance/audit lineage.
- ADR 0008 — Embedding model selection and OpenAI provider adapter You're touching embedding generation, the OpenAI adapter, or hybrid KB retrieval scoring.
- ADR 0009 — LQ.AI web shell co-exists alongside the OpenWebUI shell (does not replace it) You're working in web/, wondering why there are two chat shells, or touching LQ.AI auth/token storage.
- ADR 0010 — Gateway config hot-reload + admin write API You're touching gateway config loading, the alias write endpoints, or the gateway container's volume layout.
- ADR 0011 — Transparency-first model selection posture You're touching model routing, the model picker, per-message routing disclosure, or provider-key encryption.
- ADR 0012 — DB-backed user skills (amends ADR 0004) You're touching user-authored skills, the resolution/shadowing order, or the user_skills table.
- ADR 0013 — Autonomous Layer design influences (M4 / LQVern) You're working on the autonomous executor, the R4/R5/R6 brakes, or autonomous memory vs Project context vs the precedent board.
- Autonomous Layer You're working on autonomous sessions, the four primitives (watches/schedules/memory/precedents), or the brake/chokepoint model.
- LQ.AI — Canonical Database Schema You're changing a table/column/index, or need exact types, FK behavior, or the hybrid-retrieval scoring formula.
- LQ.AI — Observability Operator Guide You're configuring OTel/metrics, instrumenting a span, or checking which signals actually exist.
- LQ.AI — System Architecture You need the system-wide picture — what runs where, the gateway pipeline, or where data lives for procurement.
- Mini-PRD: OpenTelemetry Deepening — Trace Correlation, Domain Spans, Deployment Recipes You're picking up the OTel deepening work, or want the gap between shipped instrumentation and an operator-grade observability story.
Capabilities & Services
The features a legal team actually touches and the services that run them: the four-stage Citation Engine, Playbooks, Tabular Review, the Word add-in, the Slack/Teams intake bridges, and the README for each service (api, gateway, word-addin, the two bridges). The docs are honest about what's shipped vs. scaffold.
- Citation Engine You're touching citation verification, the message_citations table, ensemble judging, or the anonymization skip boundary.
- LQ.AI Backend API You need the backend's local run/test commands or health endpoint.
- LQ.AI Inference Gateway You need the gateway's run/test commands, its endpoint paths, or where its config schema lives.
- LQ.AI Slack Bridge (M3-D1) You need the Slack bridge's env config, run command, manifest scopes, or token-handling posture.
- LQ.AI Teams Bridge (M3-D3) You need the Teams bridge's env config, the Azure AD registration steps, or why Teams has no per-tenant encryption.
- LQ.AI Word add-in You need to build, validate, run-in-Word, or sideload the add-in, or want the per-surface roadmap.
- Playbooks You're working on playbook execution, the Easy Playbook pipeline, or the seeded built-ins.
- Slack / Teams Light Intake Bridges You're working on the Slack/Teams OAuth bridges or need their honest verification state before claiming they work.
- Tabular / Multi-Document Review You're working on the tabular grid, table-mode skills, cell extraction, or export.
- Word Add-In You're touching Word add-in install/manifest, the OAuth dialog, or the version handshake — or assessing what it actually does.
Security
The security posture as inspectable artifacts: the STRIDE threat model, the Presidio anonymization layer, append-only audit logging, the cryptographic inventory, encrypted provider keys, the Greenwood boundary-registers map, and the disclosure policy. The Inference Gateway is the trust boundary throughout.
- Anonymization Layer — operator's guide You're configuring anonymization recognizers or assessing PII-leak risk for a deployment.
- Audit Logging You're querying the audit trail or answering a 'do you log admin actions' procurement question.
- Boundary Registers — Restraint Catalog You're assessing which agentic-restraint controls are implemented vs. deferred, or attaching work to a register.
- Cryptography You're tracing a specific crypto control, algorithm, or key-rotation path.
- Dependencies & Vulnerability Monitoring You're adding a dependency or verifying a release's dependency tree for CVEs.
- Encrypted-at-Rest Provider Keys — Operator Workflow You're bootstrapping, rotating, or recovering encrypted provider keys in gateway.yaml.
- Release Verification You're verifying a downloaded release's signature, SBOM, or build provenance.
- Security Documentation You need to find which security artifact exists and its shipped-vs-deferred status.
- Security Policy You're reporting a vulnerability or need the disclosure SLAs and safe-harbor terms.
- Threat Model You're assessing the threat surface or adding a control.
Skills
Skills are the canonical artifact of value — open, attorney-attested legal work product, not hidden prompts. This category holds the authoring guide; the 14 starter skills themselves are indexed for search and deep-link into the sibling Skills Explorer for their curated, diagrammed experience.
- Acceptance Test Plan — Action Items from Client Alert v1.0.0
- Acceptance Test Plan — Comms Improver v1.0.0
- Acceptance Test Plan — Contract QA v1.0.0
- Acceptance Test Plan — DPA Checklist Review v1.0.0
- Acceptance Test Plan — Enhance Prompt v1.0.0
- Acceptance Test Plan — MSA Review — Commercial Purchase v1.0.0
- Acceptance Test Plan — MSA Review — SaaS v1.0.0
- Acceptance Test Plan — NDA Review v1.0.1
- Acceptance Test Plan — Skill Creator v1.0.0
- Acceptance Test Plan — Vendor Privacy Policy First Pass v1.0.0
- Action Items from Client Alert
- Audience Calibration
- Citation Conventions for Contract QA
- Commercial Purchase MSA Issue Checklist
- Comms Improver
- Contract QA
- Contract Snapshot
- Contributing Skills to LQ.AI
- Deadline Calibration
- DPA Checklist Review
- Enhance Prompt
- Example Session: Producing a "Board Minutes Generator" Skill
- Example — Mutual NDA extraction
- Expansion Patterns
- Extraction Patterns
- GDPR DPA Requirements
- General Commercial DPA Requirements
- HIPAA Business Associate Agreement Requirements
- Legal to Plain-Language Transformations
- MSA Review — Commercial Purchase
- MSA Review — SaaS
- MSA Snapshot
- NDA Review
- NDA Snapshot
- Perspective Lens
- Perspective Lens
- Perspective Lens
- Playbook Easy Extract
- Policy Topics
- Preserving User Voice
- Question Classification
- Red Flags
- Red Flags and Operational Issues
- Red Flags and Operational Issues
- Red Flags and Operational Issues
- SaaS MSA Issue Checklist
- Self-Improvement Instruction Template
- Severity Rubric
- Severity Rubric
- Severity Rubric
- Skill Creator
- Skill-Authoring Guide Before drafting or reviewing a skill, or designing its frontmatter and inputs.
- Standard NDA Issue Checklist
- US State Privacy DPA Requirements
- Vendor Privacy Policy First Pass
- Wizard Mode
- Worked Example — Buyer Perspective, Quick Triage Mode
- Worked Example — Clean Privacy Policy
- Worked Example — Clear Alert
- Worked Example — Customer Perspective, Vendor-Prepared SaaS MSA
- Worked Example — Customer-Facing Disclaimer
- Worked Example — Executive Briefing
- Worked Example — Expansion When a Skill Is Attached
- Worked Example — GDPR DPA Review (Controller Perspective)
- Worked Example — Multi-Jurisdiction Alert with Filtering
- Worked Example — Mutual Perspective, Early-Stage M&A NDA
- Worked Example — Privacy Policy with Red Flags
- Worked Example — Recipient Perspective, Unilateral NDA
- Worked Example — Sales Team
- Worked Example — Short Prompt Expanded
- Worked Example — Skipped Prompt
- Worked Example — Supplier Perspective, Comprehensive Mode, Automotive Industry
- Worked Example — Type A: Direct Lookup
- Worked Example — Type C: Comparison / Unusualness
- Worked Example — Type D: Scenario
- Worked Example — Type E: Multi-Issue Question
- Worked Example — US State Privacy DPA Review (Service Provider Perspective)
- Worked Example — Vague Alert
- Worked Example — Vendor Perspective, Customer-Prepared MSA Template
- Writing the Description Field
Contributing & Governance
How to contribute and how the project is governed: the engineering PR path (DCO, ruff/mypy, the test taxonomy), the Code of Conduct, the upstream-skill provenance ledger, the skill-acceptance-testing framework, and the eight short-cycle "easiest contributions" mini-PRDs, each a pre-written maintainer decision.
- Contributing to LQ.AI Before opening any engineering PR, or to find the code-style/testing/DCO rules.
- Contributor Covenant Code of Conduct To report conduct issues or to know the enforcement consequences.
- Easiest Contributions When you want to pick a short-cycle, well-scoped contribution.
- LQ.AI — Acceptance Testing Framework When you're drafting a skill test plan or running an acceptance pass.
- Mini-PRD: Acceptance Tests for the Built-in Skills To run or contribute an acceptance pass for a built-in skill.
- Mini-PRD: Air-Gap Install Verification CI Test To implement or understand the air-gap egress CI gate.
- Mini-PRD: Community Skill Installer (admin UI) To build the runtime community-skill install path.
- Mini-PRD: NIST AI RMF 1.0 Profile Mapping To author the NIST AI RMF / GenAI Profile compliance mapping.
- Mini-PRD: OpenSSF Scorecard + Best Practices Badge (Passing Tier) To add OpenSSF Scorecard + Best Practices badges and SECURITY-INSIGHTS.
- Mini-PRD: OWASP LLM Top 10 Mitigation Mapping To author the OWASP LLM Top 10 security mapping.
- Mini-PRD: Procurement-Readiness Pack To build the SIG/CAIQ procurement-response pack (DE-086).
- Mini-PRD: Reverse-Proxy + TLS Deployment Recipes To author production reverse-proxy + TLS recipes.
- NOTICES — Upstream Skill Provenance When porting an external skill, or to check a skill's upstream license and attribution.
- PULL_REQUEST_TEMPLATE
- Repo-Opening Checklist
Operations & Compliance
Running, deploying, and selling the thing: the optional OpenTelemetry observability recipes, the procurement-readiness pack (SIG Lite / CAIQ), the compliance-alignment stubs (SOC 2 / ISO / GDPR / HIPAA / FedRAMP), and the upstream-research analysis behind the skill library.
- `claude-for-legal` — review for M1 incorporation analysis You're scoping skill-library expansion, the dual slash/attach invocation model, or a community-skill installer.
- Compliance Alignment Pack You're starting compliance/certification work, or want to know which framework-alignment docs exist vs. are stubs.
- LQ.AI — Observability Deployment Recipes You're deciding which observability recipe to use, or need the no-telemetry-by-default ground truth.
- Observability recipe: Grafana + Tempo + Loki + Prometheus You're standing up the full self-hosted Tempo/Loki/Prometheus/Grafana stack or verifying a first trace.
- Observability recipe: standalone OpenTelemetry Collector You already run Honeycomb/Datadog/Lightstep (or any OTLP backend) and just need to forward LQ.AI's spans there.
- Procurement-Readiness Pack You need procurement questionnaire material or want the operator-configurable answer convention.
- SIG Lite — Privileged-Matter Handling (M2-D3 starter) + M3 External Trust Boundaries A procurement reviewer asks how LQ.AI handles privileged matters, audit logging, or the Word/Slack/Teams credentials.
- v0.4.0 — M4 release: the Autonomous Layer (opt-in), platform operability, and a docs/Learn honesty sweep You want to know what shipped in M4/v0.4.0, the brake model, or what was explicitly deferred.
Developer Tools
The documentation tooling itself — the static Repository + Skills Explorer that ships under docs/explore. (This Atlas lives alongside it and is not indexed in its own corpus.)
- Atlas doc-build log You're running an incremental Atlas update, or want to know when the curation was last refreshed and against which commit.
- Repository Explorer (`docs/explore`) You want to browse/review the docs corpus locally, or understand how the Explorer is built.
Planning & History
The working record: milestone implementation plans, dated session handoffs, the superpowers plan/spec set, the LQVern (M4) design and handoff docs, and the sample NDAs/MSAs used as fixtures. Indexed for search; not curated or drift-checked, because handoffs reference code as it stood that day.
- Backend Phase E — Release Readiness Implementation Plan
- Building aligned agentic flows in LQ.AI (M4 / LQVern contributor guide)
- Design — Honest alignment: docs + Learn (post-M4 close)
- Handoff — M4 / LQVern execution: Phase C underway → resume at Task M4-C2 (web dashboard)
- Handoff — M4 / LQVern: Phase C COMPLETE → resume at Phase D
- Handoff — M4 / LQVern: write the implementation plan + Learn-tab viz spec
- Handoff — M4 real-executor-work execution (Tasks 1–18 done) → resume at Task 19 (fresh-install acceptance)
- Handoff — M4-D2 docs + Learn honest-alignment (resume at plan Task 4) → then tag v0.4.0
- Handoff — Phase 1 (Autonomous Operability) resume at plan Task 7 → then close M4 → tag v0.4.0
- Honest Alignment: Docs + Learn — Implementation Plan
- Learn-tab "Autonomous flow" visualization — spec
- LQ.AI — M1 Frontend Design
- LQVern — M4 Autonomous Layer working folder
- M1 Build Progress
- M1 Frontend — Wave A (Practice Visual Foundation) Implementation Plan
- M1 Frontend — Wave B (Dashboard + IA + Trust + Admin Developer Support) Implementation Plan
- M1 Frontend — Wave B v2 (post-merge) Implementation Plan
- M1 Frontend — Wave C (Matters skeleton) Implementation Plan
- M1 Frontend — Wave D.2 (Skill Creator) Implementation Plan
- M1 Implementation Order
- M2 Implementation Plan — Citation Engine, Anonymization Layer, and Azure Adapter
- M3 Implementation Plan — Playbooks, Word Add-In, Tabular Review, and Slack/Teams
- M3 Phase B — Word Add-In Plumbing — Prep Notes
- M3 Phase C — Tabular / Multi-Document Review — Prep Notes
- M3-A4 Playbook Execution UI Implementation Plan
- M3-A5 Built-in Playbooks (MSA-SaaS, DPA-GDPR, MSA-Commercial-Purchase) — Prep Notes
- M3-A6 Easy Playbook Wizard — Prep Notes
- M3-F2 — Domain Spans + Rich Attributes Implementation Plan
- M3-F3 — Deployment Recipes + `docs/observability.md` + OTel-eval Playground Implementation Plan
- M4 Implementation Plan — Autonomous Layer (LQVern)
- M4 — Wire real in-loop agentic work into the Autonomous executor (design)
- M4 — Wire real in-loop agentic work into the Autonomous executor — implementation plan
- M4-C2 Autonomous Dashboard Implementation Plan
- M4-C2 — Autonomous dashboard: design
- Platform Cohesion + Autonomous Operability — Design
- Platform Cohesion Phase 1 — Autonomous Operability Implementation Plan
- Session Handoff — 2026-05-08 → 2026-05-09
- Session Handoff — 2026-05-09 (afternoon → next session)
- Session Handoff — 2026-05-09 → next session
- Session Handoff — 2026-05-10 (D7 + Wave-3 transparency pivot)
- Session Handoff — 2026-05-10 (D7 Saved Prompts)
- Session Handoff — 2026-05-10c (Option A + D3-coverage)
- Session Handoff — 2026-05-10d (D8 API slice + encrypted-keys doc)
- Session Handoff — 2026-05-10e (D8 closed loop + D8.1a teams)
- Session Handoff — 2026-05-10f (D8.1b: team-scope user-skills + middle-slot resolver)
- Session Handoff — 2026-05-10g (D8.1c: Skill Creator UI for team-scope skills)
- Session Handoff — 2026-05-11 (Frontend · Wave B kickoff)
- Session Handoff — 2026-05-11 (M1 backend gap-fill: Waves A + B + C)
- Session Handoff — 2026-05-11 Wave D (M1 backend gap-fill follow-up)
- Session Handoff — 2026-05-12 (Wave C closed; Backend Phase E queued)
- Session Handoff — 2026-05-12 (Wave D.1 + Phase E shipped; 5-item queue for next session)
- Session Handoff — 2026-05-12 evening (Items 1+2+4+5 closed; only Wave D.2 remains for M1)
- Session Handoff — 2026-05-13 evening (Wave D.2: Wave 3 closed; Wave 4–9 remain)
- Session Handoff — 2026-05-13 late evening (Wave D.2: Wave 4 closed; Waves 5-9 remain)
- Session Handoff — 2026-05-13 mid (Wave D.2: Waves 1+2 closed; Waves 3-9 remain)
- Session Handoff — 2026-05-13 night (Wave D.2: Waves 5+6+7 closed; Waves 8-9 remain)
- Session Handoff — 2026-05-14 early hours (M1 user-facing placeholders closed; Wave 8/9 + docs + Learn page remain)
- Session Handoff — 2026-05-15 — M1 verified, M2 kickoff
- Session Handoff — 2026-05-15 — Pre-v0.1.0 Tag
- Session Handoff — 2026-05-16 — M2 Phase A complete, Phase B 2/3
- Session Handoff — 2026-05-16 — M2 Phase C 2/3, frontend (M2-C2) next
- Session Handoff — 2026-05-17 — M2 shipped (v0.2.0) → M3 kickoff next
- Session Handoff — 2026-05-18 — M3 Phase 0 complete + Phase A halfway → M3-A4 kickoff next
- Session Handoff — 2026-05-19 — M3-A5 shipped + retro disclaimer alignment + dockerignore fix → M3-A6 Phase 1 (ARQ infra) kickoff next
- Session Handoff — 2026-05-19 — M3-A6 Phases 1-5 shipped (backend complete + live-verified) → Phase 6 (frontend wizard) kickoff next
- Session Handoff — 2026-05-21 (evening) — M3 Phase B plumbing shipped (PR #59) → Phase C kickoff next
- Session Handoff — 2026-05-21 (night) — M3-C1 shipped + M3-C2 substrate ready → cost.py + executor next
- Session handoff — Lavern evaluation and integration into the LQ.AI roadmap
- svelte-check Error Backlog
- Wave D.1 — In-chat power features (Enhance Prompt expansion, KB attach modal, Tier-floor refusal block, Receipts drawer)
- Wave D.1 — In-chat power features Implementation Plan
- Wave D.2 — Skill Creator (Design)