diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..1ecc94c --- /dev/null +++ b/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 — ``, `` — 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.