Add CLAUDE.md with repo guidance for AI assistants

CLAUDE.md

@@ -0,0 +1,127 @@
+# CLAUDE.md
+
+Guidance for AI assistants working in this repository.
+
+## What this repo is
+
+A **Mintlify documentation site** for the **PrivateInvest** platform — a B2B private-markets marketplace for wealth managers (IFAs). This repo contains **only documentation** (`.mdx` files + Mintlify config). It does NOT contain the application source code; the platform's actual frontend, backend, and agent code live elsewhere (referenced at `https://github.com/quicksilverj2/privex-pro`).
+
+When users ask to "fix a bug," "add a feature," or anything that implies editing application code, stop and confirm — they likely mean documentation updates, not code changes.
+
+## Repository layout
+
+```
+.
+├── docs.json          # Mintlify config: theme, navigation, tabs, anchors
+├── index.mdx          # Documentation homepage
+├── favicon.svg
+├── logo/              # light.svg + dark.svg (theme-aware logos)
+├── README.md          # Brief site overview
+├── LICENSE
+├── agent/             # Agent-system docs (Python / FastAPI / OpenAI Agent Kit)
+│   ├── introduction.mdx
+│   ├── quick-start.mdx
+│   ├── setup.mdx
+│   ├── authentication.mdx
+│   ├── api-docs.mdx
+│   ├── security-collection-guide.mdx
+│   ├── run-task-example.mdx
+│   ├── checking-logs.mdx
+│   ├── viewing-logs.mdx
+│   └── debug-security-creation.mdx
+├── backend/           # Backend API docs (Fastify / Node / Supabase Postgres)
+│   ├── setup.mdx
+│   ├── api-overview.mdx
+│   ├── database-setup.mdx
+│   ├── secret-key-setup.mdx
+│   └── swagger-troubleshooting.mdx
+└── frontend/          # Frontend docs (Next.js 14 App Router)
+    ├── overview.mdx
+    └── setup.mdx
+```
+
+Every page that appears in the site **must** be registered in `docs.json` under `navigation.tabs[].groups[].pages`. Pages are referenced **without** the `.mdx` extension (e.g. `"agent/introduction"`). Creating an `.mdx` file but forgetting to add it to `docs.json` means it won't appear in the sidebar.
+
+## The product being documented (for context)
+
+This affects terminology used across the docs — keep it consistent:
+
+- **Platform name**: PrivateInvest (not "Privex" — `privexpro.com` only shows up as seeded admin credentials)
+- **User roles**: `ADMIN`, `COMPLIANCE`, `IFA`, `DEAL_ORIGINATOR` (always uppercase in docs)
+- **Default ports**: frontend `4000`, backend `4001`, agent server `4002`
+- **Stack**: Next.js 14 App Router + Tailwind + ShadCN UI (frontend); Fastify + Supabase Postgres (backend); Python + FastAPI + OpenAI Agent Kit (agent)
+- **Three agent tasks**: `security_collection`, `client_kyc_review`, `security_compliance_review`
+- **Supabase keys**: prefer `sb_secret_...` secret keys over deprecated `service_role` JWTs
+
+## Authoring conventions
+
+### MDX frontmatter
+
+Every page starts with YAML frontmatter — both `title` and `description` are required. Match this exact shape:
+
+```mdx
+---
+title: "Page Title"
+description: "One-sentence summary used by Mintlify for SEO and previews"
+---
+
+# Page Title
+
+Body content here...
+```
+
+### Mintlify components
+
+The homepage uses Mintlify-specific JSX components — `<Card>`, `<Columns cols={N}>` — which only render correctly inside `.mdx` files served by Mintlify. Don't introduce these into plain `.md` files (the `README.md` and this `CLAUDE.md` are plain markdown).
+
+When linking between pages inside `.mdx`, use **Mintlify-style absolute paths without the extension**:
+
+- Correct: `href="/backend/setup"`, `[Backend Setup](/backend/setup)`
+- Wrong: `href="backend/setup.mdx"`, `[..](./setup.mdx)`
+
+The most recent commit on `main` (`a378ae5`) was specifically a fix to convert broken `.md`/`.mdx` relative links to this form — don't regress it.
+
+### Voice & structure
+
+- Use sentence-case headings (`## Initial Setup`, not `## INITIAL SETUP`).
+- Code blocks should carry a language fence (` ```bash`, ` ```env`, ` ```json`, ` ```sql`).
+- For setup pages, follow the existing numbered-step pattern (`1.`, `2.`, ...).
+- Cross-link between sibling docs liberally — readers navigate by clicking, not by URL.
+- Emojis appear sparingly in existing docs (`✅`, `⚠️`, `🎉`) — keep them rare and meaningful. Don't sprinkle them in new content unless mirroring an existing page's style.
+
+## Editing workflow
+
+1. Identify the right file. The navigation in `docs.json` is the source of truth for what's published.
+2. Edit the `.mdx` file with the `Edit` tool (prefer Edit over Write — these files are short and targeted edits keep diffs reviewable).
+3. If adding a new page:
+   - Create the `.mdx` file under the appropriate subdirectory.
+   - **Also** add its path (without `.mdx`) to the correct group in `docs.json` — otherwise it won't appear in the sidebar.
+4. If renaming or moving a page, update both the file path and its entry in `docs.json`, plus any `href="/old/path"` references in other `.mdx` files.
+
+## Local preview
+
+Mintlify is not installed in this container. The README documents the workflow for contributors:
+
+```bash
+npm i -g mint
+mint dev   # http://localhost:3000
+```
+
+Don't try to run `mint dev` from this environment unless the user explicitly asks — outbound network access may be restricted and there's no `package.json` here to install from. Trust the docs.json schema and your edits; the user will preview locally.
+
+Deployment is automatic: pushes to `main` trigger Mintlify's GitHub app to publish.
+
+## Git workflow (this session)
+
+- **Designated working branch**: `claude/add-claude-documentation-96O8O`. All commits and pushes go here unless the user says otherwise.
+- Push with `git push -u origin claude/add-claude-documentation-96O8O`.
+- After pushing, open a **draft** PR against `main` if one doesn't exist (use `mcp__github__create_pull_request`; this repo has no `gh` CLI).
+- Only the `quicksilverj2/docs` repository is reachable via GitHub MCP — don't try to access others.
+- Don't commit unless the user asks for it.
+
+## Things to avoid
+
+- **Don't invent product details.** The `.mdx` files are the canonical product description in this repo — if a user asks a factual question about the platform, answer from these files rather than guessing. If the docs are silent, say so.
+- **Don't create planning/status/implementation-summary docs.** Commit `6c45942` explicitly removed those; the docs are deliberately scoped to Agent / Backend / Frontend reference material.
+- **Don't change `docs.json` schema fields** (`theme`, `colors`, `contextual`, `logo`, etc.) unless asked — they reflect deliberate branding choices.
+- **Don't add the model identifier** (`claude-opus-4-7[1m]` etc.) to commit messages, PR titles/bodies, or any committed file.