constellai 0.3.0

package/docs/en/PUBLIC_API.md

@@ -0,0 +1,315 @@
+[← Docs index](./README.md) · [🇧🇷 Português](../pt/PUBLIC_API.md) · [✦ Constella](../../README.md)
+
+# 🛰️ Public API — driving the ship from orbit
+
+![](../assets/divider-orbit.svg)
+
+A small, honest REST surface (`/api/v1`) that lets external systems — scripts, CI jobs, a phone, or an MCP server — read project state and steer the constellation without a browser session. One bearer credential (a **Personal Access Token**), one dispatcher, one error envelope.
+
+---
+
+## When to use ✦
+
+Use the Public API when you want to drive Constella from **outside** the web UI:
+
+- A **CI pipeline** that approves a plan or flips 24/7 execution after a green build.
+- A **mobile / shell script** that polls the morning review and counts.
+- An **MCP host** (Claude Desktop, Cursor, …) — the bundled MCP server (see [MCP.md](./MCP.md)) is a thin outbound wrapper over exactly these v1 routes.
+- A **status board** that lists goals, issues, tasks or specs.
+- Asking the **Knowledge Base** a question programmatically.
+
+If you instead want an external AI host to *consume* Constella as tools, you do not call these routes by hand — you point the MCP server at them. The two are the same surface seen from two distances.
+
+---
+
+## How it works 🌌
+
+The whole API is **one dynamic catch-all route**: `src/app/api/v1/[[...path]]/route.ts`. It exports just `GET` and `POST`; both funnel into a single `dispatch()` function so that **authentication, scope, rate-limit and the response envelope live in exactly one place**.
+
+Mutations do **not** reinvent logic. They reuse the same session-less cores the Telegram remote control uses:
+
+- `approvePlanFor`, `setAuto247For`, `requestPlanChangesFor`, `reviewSummaryFor` → `src/server/plan-ops.ts`
+- `cancelGoalFor`, `archiveGoalFor` → `src/server/work-ops.ts`
+- `startNewWorkFor` → `src/server/planner-core.ts`
+- `kbAnswer` → `src/server/kb.ts`
+- Structured reads (`apiStatus`, `apiGoals`, `apiIssues`, `apiTasks`, `apiSpecs`) → `src/server/api/service.ts`
+
+There is **no session, no cookie** on the v1 routes. The only credential is the PAT. The route also sets `runtime = "nodejs"` and `dynamic = "force-dynamic"` (it touches the database on every request).
+
+### Response envelope
+
+Every response is JSON with a uniform shape:
+
+| Field   | Type      | Meaning                                  |
+| ------- | --------- | ---------------------------------------- |
+| `ok`    | `boolean` | `true` on success, `false` on error      |
+| `data`  | any       | present when `ok: true`                  |
+| `error` | `string`  | present when `ok: false`                 |
+
+```jsonc
+// success
+{ "ok": true, "data": { /* … */ } }
+// error
+{ "ok": false, "error": "this token has read scope; a write-scope token is required" }
+```
+
+---
+
+## Authentication 🔑 — Personal Access Tokens (`cn_…`)
+
+A PAT is minted in the web UI (`createPAT` in `src/server/actions/profile-actions.ts`) and stored **hashed**, never in plaintext.
+
+```ts
+// profile-actions.ts (minting)
+const raw = "cn_" + randomBytes(24).toString("base64url");
+const tokenHash = createHash("sha256").update(raw).digest("hex");
+// stored: { tokenHash, prefix: raw.slice(0,7), scope, name, userId }
+```
+
+Key properties:
+
+- **Format** — `cn_` followed by a URL-safe base64 string (24 random bytes). The route accepts `cn_[A-Za-z0-9_-]{8,}`.
+- **Shown once** — the raw `cn_…` value is returned by `createPAT` and displayed a single time. Only its **SHA-256 hash** (`tokenHash`) and a 7-char display `prefix` (e.g. `cn_a1b2`) are persisted in the `personalAccessToken` table. Lose it and you mint a new one.
+- **Never logged** — `authenticatePAT` only ever hashes the incoming token and matches the hash; the plaintext token never reaches a log line.
+- **Scope** — `read` (default) or `write`. Reads are open to any valid token; mutations require `write`.
+- **Usage stamp** — every authenticated call best-effort updates `lastUsedAt` (a write hiccup never blocks auth).
+
+### The handshake (`authenticatePAT`)
+
+`src/server/api/pat-auth.ts` runs on every request:
+
+1. Parse `Authorization: Bearer cn_…`. Malformed → **401** `missing or malformed bearer token`.
+2. SHA-256 the token, look it up by `tokenHash`. No match → **401** `invalid token`.
+3. Resolve the token owner's org via `getActiveOrg(userId, X-Constella-Org)`. This is a **membership join** — an `X-Constella-Org` value the user does not belong to is *ignored* (falls back to their first org), so a token can never be pointed at a foreign tenant. No org → **404**.
+4. Archived org → **409** `organization is archived`.
+5. Resolve the org's workspace via `getWorkspace`. None → **404**.
+
+On success the request carries `{ userId, tokenId, scope, org, workspace }`.
+
+### `X-Constella-Org`
+
+Optional header. If a user belongs to multiple organizations, set `X-Constella-Org: <orgId>` to choose which one the token acts on. Omitted (or invalid) → the user's **first** org. The choice is always validated through the membership join.
+
+---
+
+## Rate limiting 🪐
+
+A best-effort **sliding 60-second window**, keyed by `tokenId`, lives in memory in the single Next server process:
+
+```ts
+const RL_MAX = 120; // requests per token per 60s
+```
+
+Exceeding it returns **429** `rate limit exceeded (120 req/min)`. Because the counter is in-memory, a server restart resets it — acceptable for the single-operator design. There is no per-IP limit and no `Retry-After` header.
+
+---
+
+## Authorization flow 🌠
+
+```mermaid
+flowchart TD
+  A["Request → /api/v1/…"] --> B{"Bearer cn_… present & well-formed?"}
+  B -- no --> E401["401 missing/malformed"]
+  B -- yes --> C["sha256(token) → match tokenHash"]
+  C -- no match --> E401b["401 invalid token"]
+  C -- match --> D["getActiveOrg(userId, X-Constella-Org)\nmembership join"]
+  D -- none --> E404["404 no organization"]
+  D -- archived --> E409["409 archived"]
+  D -- ok --> R{"rate limit\n(120/min)?"}
+  R -- exceeded --> E429["429 rate limit"]
+  R -- ok --> M{"method + route"}
+  M -- "GET" --> RD["read services"]
+  M -- "POST (write?)" --> W{"scope == write?"}
+  W -- no --> E403["403 write scope required"]
+  W -- yes --> MUT["plan-ops / work-ops / planner-core"]
+```
+
+---
+
+## Endpoints 📡
+
+Base URL is your Constella host, e.g. `http://localhost:3000/api/v1`. All routes require the `Authorization` header; write routes additionally require a `write`-scope token.
+
+### GET (read scope is enough)
+
+| Method | Path                | Returns                                                            |
+| ------ | ------------------- | ----------------------------------------------------------------- |
+| GET    | `/api/v1` or `/me`  | `{ user, org{id,name}, workspace{id,name,slug}, scope }`          |
+| GET    | `/api/v1/status`    | counts: goals, issues (`byCol`), tasks (`byCol`), plan summary    |
+| GET    | `/api/v1/review`    | `{ text }` — the mobile-style review summary (`reviewSummaryFor`) |
+| GET    | `/api/v1/goals`     | `[{ id, title, status, progress }]`                               |
+| GET    | `/api/v1/issues`    | `[{ id, key, title, col, prio, points, moscow, approved }]`       |
+| GET    | `/api/v1/tasks`     | `[{ id, key, title, col, prio }]`                                 |
+| GET    | `/api/v1/specs`     | `[{ id, key, title, status, approved }]`                          |
+| GET    | `/api/v1/kb?q=…`    | `{ text, sources }` — Knowledge Base answer (`kbAnswer`)          |
+
+### POST (write scope, except `kb`)
+
+| Method | Path                          | Body                       | Effect                                              |
+| ------ | ----------------------------- | -------------------------- | --------------------------------------------------- |
+| POST   | `/api/v1/plan/approve`        | —                          | Approve the plan, queue tasks (`approvePlanFor`)    |
+| POST   | `/api/v1/plan/reject`         | `{ reason? }`              | Send the plan back with notes (`requestPlanChangesFor`) |
+| POST   | `/api/v1/execution`           | `{ on?: boolean }`         | 24/7 autonomous execution on/off (`setAuto247For`) — defaults `on:true` |
+| POST   | `/api/v1/work`                | `{ brief, title? }`        | Start a new unit of work (`startNewWorkFor`)        |
+| POST   | `/api/v1/goals/{id}/cancel`   | —                          | Cancel a goal (`cancelGoalFor`)                     |
+| POST   | `/api/v1/goals/{id}/archive`  | —                          | Archive a goal (`archiveGoalFor`)                   |
+| POST   | `/api/v1/kb`                  | `{ q }`                    | Knowledge Base answer — **read-ish, no write scope needed** |
+
+> `POST /api/v1/kb` is the deliberate exception: it mutates nothing, so it does not demand a `write` token. Every other POST does.
+
+---
+
+## Examples 🌠
+
+Export your token once:
+
+```bash
+export CN_TOKEN="cn_xxxxxxxxxxxxxxxxxxxxxxxx"
+export CN_BASE="http://localhost:3000/api/v1"
+```
+
+### Who am I
+
+```bash
+curl -s "$CN_BASE/me" -H "Authorization: Bearer $CN_TOKEN"
+# { "ok": true, "data": { "user": "…", "org": { "id": "…", "name": "Acme" },
+#   "workspace": { "id": "…", "name": "web", "slug": "web" }, "scope": "write" } }
+```
+
+### Project status & morning review
+
+```bash
+curl -s "$CN_BASE/status" -H "Authorization: Bearer $CN_TOKEN"
+curl -s "$CN_BASE/review" -H "Authorization: Bearer $CN_TOKEN"
+```
+
+### List boards
+
+```bash
+curl -s "$CN_BASE/goals"  -H "Authorization: Bearer $CN_TOKEN"
+curl -s "$CN_BASE/issues" -H "Authorization: Bearer $CN_TOKEN"
+curl -s "$CN_BASE/tasks"  -H "Authorization: Bearer $CN_TOKEN"
+curl -s "$CN_BASE/specs"  -H "Authorization: Bearer $CN_TOKEN"
+```
+
+### Ask the Knowledge Base
+
+```bash
+# GET form (query string)
+curl -s "$CN_BASE/kb?q=how%20do%20we%20handle%20auth" -H "Authorization: Bearer $CN_TOKEN"
+
+# POST form (JSON body) — also no write scope required
+curl -s -X POST "$CN_BASE/kb" \
+  -H "Authorization: Bearer $CN_TOKEN" -H "Content-Type: application/json" \
+  -d '{"q":"how do we handle auth"}'
+```
+
+### Approve / reject a plan (write scope)
+
+```bash
+curl -s -X POST "$CN_BASE/plan/approve" -H "Authorization: Bearer $CN_TOKEN"
+
+curl -s -X POST "$CN_BASE/plan/reject" \
+  -H "Authorization: Bearer $CN_TOKEN" -H "Content-Type: application/json" \
+  -d '{"reason":"split the auth issue in two"}'
+```
+
+### Toggle 24/7 execution (write scope)
+
+```bash
+curl -s -X POST "$CN_BASE/execution" \
+  -H "Authorization: Bearer $CN_TOKEN" -H "Content-Type: application/json" \
+  -d '{"on":true}'
+# { "ok": true, "data": { "auto247": true } }
+```
+
+### Launch new work (write scope) 🚀
+
+```bash
+curl -s -X POST "$CN_BASE/work" \
+  -H "Authorization: Bearer $CN_TOKEN" -H "Content-Type: application/json" \
+  -d '{"title":"Password reset","brief":"Add a forgot-password flow with email tokens"}'
+```
+
+### Cancel / archive a goal (write scope) 🕳️
+
+```bash
+curl -s -X POST "$CN_BASE/goals/$GOAL_ID/cancel"  -H "Authorization: Bearer $CN_TOKEN"
+curl -s -X POST "$CN_BASE/goals/$GOAL_ID/archive" -H "Authorization: Bearer $CN_TOKEN"
+```
+
+### Pointing a token at a specific org
+
+```bash
+curl -s "$CN_BASE/status" \
+  -H "Authorization: Bearer $CN_TOKEN" \
+  -H "X-Constella-Org: $ORG_ID"
+```
+
+---
+
+## Possible states 🛰️
+
+| HTTP | `error`                                                   | Cause                                                       |
+| ---- | -------------------------------------------------------- | ---------------------------------------------------------- |
+| 200  | —                                                        | success (`ok: true`)                                       |
+| 400  | `missing ?q=` / `missing body.q`                         | KB query with no question                                  |
+| 400  | `could not start work` (or core message)                | `POST /work` with empty `brief`                            |
+| 401  | `missing or malformed bearer token`                      | no `Authorization`, or not `Bearer cn_…`                   |
+| 401  | `invalid token`                                          | token hash not in `personalAccessToken`                    |
+| 403  | `this token has read scope; a write-scope token is required` | mutating route with a `read` token                     |
+| 404  | `no organization for this token's user`                  | token owner has no org                                     |
+| 404  | `no workspace for the organization`                      | org has no workspace                                       |
+| 404  | `unknown GET /…` / `unknown POST /…` / `goal not found`  | bad route or missing goal                                  |
+| 409  | `organization is archived`                               | the org behind the token is archived                       |
+| 429  | `rate limit exceeded (120 req/min)`                      | more than 120 requests/token in 60s                        |
+| 500  | (error message)                                          | unexpected exception (caught at the `GET`/`POST` boundary) |
+
+---
+
+## Related integrations 🌌
+
+- **[MCP.md](./MCP.md)** — the outbound MCP server (`scripts/mcp-server.mjs`) is a stdio wrapper over these exact routes; an external AI host drives Constella through it using the same `cn_…` PAT.
+- **[TELEGRAM.md](./TELEGRAM.md)** — the Telegram remote control shares the very same session-less cores (`plan-ops.ts`, `work-ops.ts`, `planner-core.ts`).
+- **[CHAT_COMMANDS.md](./CHAT_COMMANDS.md)** — the slash commands map to the same actions you reach over HTTP here.
+- **[WORKFLOW.md](./WORKFLOW.md)** / **[GOALS_SPECS_ISSUES.md](./GOALS_SPECS_ISSUES.md)** — the Goal → Spec → Issue → Plan lifecycle that `status`, `plan/approve` and `work` operate on.
+
+---
+
+## Security 🕳️
+
+- **Hashed at rest** — only the SHA-256 `tokenHash` and a 7-char display `prefix` are stored; the raw `cn_…` is shown once and never persisted or logged.
+- **Tenant isolation** — `getActiveOrg` joins through `member`, so a token can only act on orgs its owner belongs to; a forged `X-Constella-Org` is silently ignored.
+- **Scope gate** — every mutation calls `needWrite()` and returns **403** for `read` tokens. The only POST that skips it is `/kb` (a pure read).
+- **Revocation** — `revokePAT` (profile UI) deletes the row; the next request with that token gets **401 invalid token**.
+- **No session bleed** — the v1 routes never read cookies or sessions; a stolen browser session cannot be replayed here, and a stolen PAT cannot reach the authenticated web UI.
+- **Transport** — there is no built-in TLS. Behind `start`/`auth` mode the server binds loopback (`127.0.0.1`); for `vps`/`portable` (bind `0.0.0.0`) put it behind a TLS reverse proxy / tailnet and treat the PAT as a password. See [SECURITY.md](./SECURITY.md), [VPS_MODE.md](./VPS_MODE.md).
+
+---
+
+## Troubleshooting 🛠️
+
+| Symptom                                   | Likely cause / fix                                                                 |
+| ----------------------------------------- | ---------------------------------------------------------------------------------- |
+| `401 missing or malformed bearer token`   | Header must be exactly `Authorization: Bearer cn_…`; check for a stray space/quote. |
+| `401 invalid token`                       | Token revoked or mistyped. Mint a fresh one in **Profile → Personal Access Tokens**; it is shown once. |
+| `403 … write-scope token is required`     | You used a `read` token on a mutation. Create a `write`-scope token.               |
+| `404 no organization` / `no workspace`    | The token's user has no org/workspace yet — finish [ONBOARDING.md](./ONBOARDING.md). |
+| `409 organization is archived`            | Un-archive the org, or use a token whose org is active.                            |
+| `429 rate limit exceeded`                 | You crossed 120 req/min for that token; back off (the window is a sliding 60s).    |
+| Wrong org's data returned                 | Pass `X-Constella-Org: <orgId>`; an invalid value falls back to the first org.     |
+| `400 missing ?q=` / `missing body.q`      | KB needs a non-empty question — `?q=…` for GET, `{"q":"…"}` for POST.              |
+| Connection refused from another machine   | In `start`/`auth` mode the server is loopback-only; use `vps`/`portable` or a proxy. |
+
+---
+
+## Related links
+
+- [MCP.md](./MCP.md) — outbound MCP server over these routes
+- [TELEGRAM.md](./TELEGRAM.md) — Telegram remote control (shared cores)
+- [CHAT_COMMANDS.md](./CHAT_COMMANDS.md) — slash commands
+- [WORKFLOW.md](./WORKFLOW.md) — the work lifecycle
+- [GOALS_SPECS_ISSUES.md](./GOALS_SPECS_ISSUES.md) — goals, specs, issues
+- [SECURITY.md](./SECURITY.md) — vault, secrets, auth
+- [VPS_MODE.md](./VPS_MODE.md) · [PORTABLE_MODE.md](./PORTABLE_MODE.md) — remote / portable binds
+- [CONFIGURATION.md](./CONFIGURATION.md) — env vars and ports

package/docs/en/PUBLISHING.md

@@ -0,0 +1,343 @@
+[← Docs index](./README.md) · [🇧🇷 Português](../pt/PUBLISHING.md) · [✦ Constella](../../README.md)
+
+# 🚀 Publishing & Distribution — launching the ship from the shipyard
+
+![](../assets/divider-orbit.svg)
+
+Publishing is how the central ship leaves the shipyard. Two launches happen, in two directions: the **npm tarball** carries the *compiled runtime* to end users, and the **public Git mirror** carries the *product tree* (docs, launcher, migrations — no source) to `github.com/gabriel7silva/constella`. The private development tree stays home, in orbit, on the `dev` remote. ✦
+
+> **TL;DR** — End users receive a compiled, minified runtime, **never `src/`**. `npm publish` ships the prebuilt `.next`; `scripts/publish-public.mjs --push` mirrors a clean, secret-scanned, source-free tree to the public Git repo. Both refuse to ship secrets.
+
+---
+
+## When to use
+
+| You want to… | Use |
+| --- | --- |
+| Ship a new version to npm (`npx constellai` users) | `npm publish` (runs `prepublishOnly` → `prepack`) |
+| Mirror the product tree to the public Git repo | `node scripts/publish-public.mjs --push` |
+| Dry-run the public mirror (scan only, no push) | `node scripts/publish-public.mjs` |
+| Verify the tarball locally before publishing | `npm pack` (runs `prepack` → `trim-next`) |
+| Strip dev artifacts from a build before packing | automatic on `prepack`; manual: `node scripts/trim-next.mjs` |
+| Remove scratch/dead files from the repo root | `npm run clean` (`scripts/clean-repo.mjs`) |
+
+This page covers the **two distribution channels** and the gates that protect them. For the user-facing update path, see [UPDATE](./UPDATE.md). For the secret-scanning machinery, see [SECURITY](./SECURITY.md). For deploying a *built product* (not Constella itself), see [DEPLOY](./DEPLOY.md) and [PREPARE_DEPLOY](./PREPARE_DEPLOY.md).
+
+---
+
+## How it works 🌌
+
+Constella distributes through **two channels** that share one principle: *ship the product, never the source.*
+
+```
+            ┌────────────────────── dev tree (private) ──────────────────────┐
+            │  src/   e2e/   tests   playwright.config.ts   drizzle/  bin/    │
+            │  .next/ (built)   docs/   skills/   scripts/   *.config.mjs     │
+            └────────────────────────────────────────────────────────────────┘
+                         │                                   │
+        npm publish      │                                   │   publish-public.mjs --push
+   (prepublishOnly →     │                                   │   (clean-tree + secret-scan)
+        prepack)         ▼                                   ▼
+   ┌─────────────────────────────┐               ┌────────────────────────────────┐
+   │ npm registry: constellai    │               │ public Git: gabriel7silva/      │
+   │ COMPILED runtime tarball     │               │ constella (force-pushed mirror) │
+   │ .next + bin + drizzle + docs │               │ docs + bin + drizzle + skills   │
+   │ NO src/                      │               │ NO src/, NO .next, NO secrets   │
+   └─────────────────────────────┘               └────────────────────────────────┘
+```
+
+1. **npm channel** — `npm publish` ships the runtime as a tarball. The `files` allowlist in `package.json` selects exactly what travels; `prepublishOnly` validates the tree; `prepack` (`trim-next.mjs`) strips dev artifacts from `.next` so end users receive only the production runtime.
+2. **Git channel** — `scripts/publish-public.mjs` builds a filtered tree in a *temporary* git index (HEAD minus `src/`/tests, plus the generated `drizzle/` migrations), secret-scans exactly that set, and **force-pushes** it as a fresh root commit to the `public` remote. The compiled `.next` does **not** travel through git — it reaches users via the npm tarball.
+3. **Dual-repo** — the private `dev` remote (`constella-Dev`) keeps the full source history; the `public` remote (`constella`) is a clean, disposable mirror, not a shared history.
+
+> Neither channel carries `src/`. The schema reaches users as generated SQL under `drizzle/`, applied by `drizzle-kit migrate`. See [INSTALLATION](./INSTALLATION.md).
+
+---
+
+## Main flow 🌠
+
+```mermaid
+flowchart TD
+  subgraph DEV["Dev tree (this repo, dev remote)"]
+    SRC["src/ + e2e/ + tests + configs"]
+    BUILT[".next (next build --webpack)"]
+    DRZ["drizzle/ (generated SQL migrations)"]
+    SHIP["bin/ scripts/ skills/ docs/ *.config.mjs"]
+  end
+
+  SRC --> NPMHOOK
+  BUILT --> NPMHOOK
+  DRZ --> NPMHOOK
+  SHIP --> NPMHOOK
+
+  subgraph NPM["npm channel — npm publish"]
+    NPMHOOK["prepublishOnly: drizzle-kit generate + validate (typecheck + parity + build)"]
+    PREPACK["prepack: trim-next.mjs strips .next/dev,cache,trace"]
+    TAR["files allowlist → tarball"]
+    NPMHOOK --> PREPACK --> TAR
+  end
+
+  SRC --> PUBHOOK
+  DRZ --> PUBHOOK
+  SHIP --> PUBHOOK
+
+  subgraph GIT["Git channel — publish-public.mjs"]
+    PUBHOOK["ls-files minus EXCLUDE + force-add drizzle/"]
+    SCAN["secret-scan exact publish set"]
+    GATE{"findings == 0 ?"}
+    TREE["temp git index → write-tree → commit-tree"]
+    PUSH["git push -f public commit:refs/heads/main"]
+    PUBHOOK --> SCAN --> GATE
+    GATE -- "no" --> ABORT["exit 1 — refuse"]
+    GATE -- "yes (--push)" --> TREE --> PUSH
+  end
+
+  TAR --> REG["npm registry: constellai"]
+  PUSH --> PUB["public Git mirror"]
+```
+
+---
+
+## Key concepts 🪐
+
+### The `files` allowlist (`package.json`)
+
+npm packs **only** what `files` lists (plus a few always-included files). This is the single source of truth for "what an end user receives":
+
+```json
+"files": [
+  ".next", "bin", "scripts", "skills", "docs",
+  "drizzle", "next.config.mjs", "drizzle.config.mjs",
+  "README.md", "LICENSE", "CHANGELOG.md"
+]
+```
+
+`src/` is **absent by design**. The package comment makes the intent explicit:
+
+> *"Ships the COMPILED build (`.next`) + generated migrations (`drizzle`) + the launcher — NOT `src/`. End users get a compiled, minified runtime, never the source. `next.config` is `.mjs` so `next start` needs no TypeScript at runtime (devDeps aren't installed for end users)."*
+
+### `prepack` → `trim-next.mjs`
+
+`prepack` runs on `npm pack` and `npm publish`, right before the tarball is built. `scripts/trim-next.mjs` deletes the parts of `.next` that `next start` does **not** need:
+
+| Removed from `.next/` | Why |
+| --- | --- |
+| `dev` | Turbopack dev-server output + a multi-GB development log; regenerated by `next dev`. |
+| `cache` | Build cache; regenerated by `next build`. |
+| `trace` | Build trace files; not needed at runtime. |
+
+Because the `files` allowlist re-includes the **whole** `.next` directory (overriding nested `.npmignore` rules), deleting these *on disk before packing* is the reliable way to keep the tarball small and clean. If `.next/` doesn't exist, the script exits 0 with a skip notice.
+
+### `prepublishOnly` → `validate`
+
+`prepublishOnly` runs **only** on `npm publish` (not on plain `npm pack`). It is the publish gate:
+
+```json
+"prepublishOnly": "drizzle-kit generate --config drizzle.config.mjs && npm run validate"
+```
+
+…where `validate` is:
+
+```json
+"validate": "npm run typecheck && npm run parity && npm run build"
+```
+
+| Step | Command | Guarantees |
+| --- | --- | --- |
+| Generate migrations | `drizzle-kit generate` | `drizzle/` reflects the current `schema.ts` before it ships. |
+| Typecheck | `tsc --noEmit` | The source compiles cleanly. |
+| i18n parity | `node scripts/i18n-parity.mjs` | EN ↔ PT dictionary keys match (see [CONFIGURATION](./CONFIGURATION.md)). |
+| Build | `next build --webpack` | A fresh, current `.next` exists to be packed. |
+
+### `publish-public.mjs` — the clean Git mirror
+
+`scripts/publish-public.mjs` produces the **source-free** Git mirror. It never runs automatically; you invoke it deliberately.
+
+The constant that defines the whole point:
+
+```js
+const EXCLUDE = ["src", "playwright.config.ts", "e2e", "tests"];
+```
+
+Flow inside the script:
+
+1. **Ensure migrations exist** — if `drizzle/` is missing or has no `.sql`, run `npx drizzle-kit generate`. The public repo ships these so an end user builds a fresh DB via `drizzle-kit migrate`.
+2. **Compute the publish set** — `git ls-files` (tracked files) minus `EXCLUDE`, **plus** the on-disk `drizzle/` files (gitignored in the dev repo, force-added into the public tree). Deduped into `publishFiles`.
+3. **Secret-scan exactly that set** — sensitive filenames + high-confidence inline patterns (mirror of `src/server/git-scan.ts`). Any finding → abort.
+4. **Belt-and-suspenders** — explicitly check that no `src/` file slipped in; if so, append a finding and abort.
+5. **Dry run by default** — without `--push`, print the file count and exit 0. With `--push`, continue.
+6. **Build the filtered tree** in a temporary git index (`GIT_INDEX_FILE`): `git read-tree HEAD` → `git rm -r --cached` each `EXCLUDE` path → `git add -f drizzle` → `git write-tree` → `git commit-tree` (a fresh root commit, no shared history).
+7. **Force-push** the bare commit to a fully-qualified ref: `git push -f public <commit>:refs/heads/main`.
+
+### Secret-scan rules (the publish gate)
+
+`publish-public.mjs` carries an inline mirror of the repository scanner. It blocks on **any** finding:
+
+| Category | Examples / pattern intent |
+| --- | --- |
+| Sensitive **files** | `.env` (and `.env.*` except `.example`/`.sample`/`.template`/`.dist`), `id_rsa`/`id_dsa`, `*.pem`/`*.key`/`*.p12`/`*.pfx`/`*.keystore`/`*.jks`/`*.ppk`/`*.asc`, `credentials*.json`, `service-account*.json`, `*.sql`/`*.dump`/`*.bak`/`*.sqlite*`/`*.db`, `npm-debug.log`, `*.local` |
+| Allowed exceptions | `.env.example`/`.sample`/`.template`/`.dist`, `.env-example`; and `drizzle/*.sql` (DDL migrations, not DB dumps) |
+| Inline secrets | AWS access key (`AKIA…`), GitHub token (`gh[posru]_…`), GitHub fine-grained PAT (`github_pat_…`), OpenAI/Anthropic key (`sk-…`), Google API key (`AIza…`), Slack token (`xox[baprs]-…`), private-key block (`-----BEGIN … PRIVATE KEY-----`), JWT (`eyJ…`), DB URL with non-placeholder creds, Telegram bot token (`\d{6,}:…`) |
+| Source leak | any path equal to `src` or starting with `src/` |
+
+> Scanned files are skipped if non-text (only `.js/.ts/.json/.md/.css/.yaml/.toml/.sh/.env/.txt/.html` are read) or larger than **512 KB**. Placeholder credentials (`user`, `admin`, `changeme`, `xxx`, `your…`, `localhost`, …) do **not** count as a DB-URL secret.
+
+### Dual-repo (public vs dev) 🕳️
+
+| Remote | Repository | Contains | History |
+| --- | --- | --- | --- |
+| `dev` | `gabriel7silva/constella-Dev` | Full private source tree (`src/`, tests, e2e, history) | Real, preserved |
+| `public` | `gabriel7silva/constella` | Product only (docs, `bin/`, `drizzle/`, `skills/`, configs) | Disposable — overwritten by force-push |
+
+The public mirror is **not** a shared-history collaboration target. Each `--push` writes a fresh root commit and force-overwrites `main`. Development happens against `dev`; the npm tarball is published separately from either git push.
+
+---
+
+## Step-by-step 🛰️
+
+### Publish a new npm version
+
+```bash
+# 1. Make sure the working tree is clean and the version is bumped in package.json.
+# 2. Publish — prepublishOnly + prepack run automatically:
+npm publish
+#    prepublishOnly: drizzle-kit generate && (typecheck + parity + build)
+#    prepack:        trim-next.mjs strips .next/{dev,cache,trace}
+#    files allowlist: .next, bin, scripts, skills, docs, drizzle, configs, README, LICENSE, CHANGELOG
+```
+
+> `package.json` is currently `"private": true` (the `//private` note: *"Keep true until the npm account exists; flip to false (or remove) to publish."*). npm refuses to publish a private package until that flag is cleared. `publishConfig.access` is already `"public"`.
+
+To verify the exact tarball contents **without** publishing:
+
+```bash
+npm pack            # runs prepack → trim-next; writes constellai-0.1.0.tgz
+tar -tf constellai-0.1.0.tgz | sort   # inspect what would ship — confirm no src/
+```
+
+### Mirror the clean tree to the public Git repo
+
+```bash
+# Dry run — generate migrations if needed, compute the publish set, secret-scan, print the count:
+node scripts/publish-public.mjs
+#   ✓ Clean: <N> files to publish (no src/, no secrets). Migrations: <M> file(s).
+
+# Push — build the filtered tree in a temp index and force-push to public main:
+node scripts/publish-public.mjs --push
+#   ✓ Pushed. The npm tarball (with the prebuilt .next) is published separately via `npm publish`.
+```
+
+### Housekeeping before either channel
+
+```bash
+npm run clean    # scripts/clean-repo.mjs — removes scratch artifacts at the repo root
+```
+
+`clean-repo.mjs` is idempotent and conservative: it only deletes a known set — `Constella App.html`, `extracted_design_system.css`, `tsconfig.tsbuildinfo`, and `temp_*.{js,ts,jsx,tsx,html,css}` — never source or config.
+
+---
+
+## Examples 🌠
+
+**A clean dry-run:**
+
+```text
+$ node scripts/publish-public.mjs
+✓ Clean: 412 files to publish (no src/, no secrets). Migrations: 7 file(s).
+
+Dry run. To publish the clean compiled tree to the public repo, run:
+  node scripts/publish-public.mjs --push
+```
+
+**A blocked run (the gate doing its job):**
+
+```text
+$ node scripts/publish-public.mjs
+✖ Refusing to publish — 2 potential secret/sensitive/source finding(s):
+  - docs/notes/scratch.md: Telegram bot token
+  - private.pem: sensitive file
+```
+
+Nothing is pushed; the script exits `1`. Fix the findings (move them out of the publish set, redact, or add a legitimate allow-path) and re-run the dry run until it reports clean.
+
+**Trimming during a pack:**
+
+```text
+$ npm pack
+• trim-next: removed .next/dev
+• trim-next: removed .next/cache
+• trim-next: removed .next/trace
+• trim-next: .next trimmed to the production runtime.
+constellai-0.1.0.tgz
+```
+
+---
+
+## Possible states 🪐
+
+| State | Channel | Meaning | Exit |
+| --- | --- | --- | --- |
+| `Clean: N files to publish` | Git (dry run) | Publish set computed, no findings; nothing pushed | `0` |
+| `Pushed` | Git (`--push`) | Filtered tree force-pushed to `public main` | `0` |
+| `Refusing to publish — N finding(s)` | Git | A secret/sensitive/source path was detected | `1` |
+| `src/ leaked into the public tree` | Git | A `src/` path slipped into the publish set | `1` |
+| `trim-next: no .next/ — nothing to trim` | npm (`prepack`) | No build present; skip silently | `0` |
+| `trim-next: .next trimmed…` | npm (`prepack`) | Dev/cache/trace removed from the build | `0` |
+| `Generating DB migrations (drizzle/)…` | Git | `drizzle/` was missing; regenerated before scanning | continues |
+
+---
+
+## Related integrations 🛰️
+
+| Integration | Relationship to publishing |
+| --- | --- |
+| **`drizzle-kit`** | `prepublishOnly` and `publish-public.mjs` both regenerate migrations under `drizzle/` so the schema ships as SQL, not TypeScript. |
+| **Secret scanner** (`src/server/git-scan.ts`) | `publish-public.mjs` inlines a mirror of its rules; the same engine guards [GITHUB](./GITHUB.md) commits and [PREPARE_DEPLOY](./PREPARE_DEPLOY.md) exports. |
+| **Update path** ([UPDATE](./UPDATE.md)) | Users pull new versions from the npm registry the tarball is published to (`registry.npmjs.org/constellai/latest`). |
+| **i18n parity** ([CONFIGURATION](./CONFIGURATION.md)) | `validate` runs `i18n-parity.mjs`, blocking a publish on EN ↔ PT key drift. |
+
+---
+
+## Security 🕳️
+
+Publishing is a high-trust operation; the design assumes a mistake *will* happen and stops it at the gate.
+
+- **Source never ships.** Both channels exclude `src/`. The Git mirror checks twice — `EXCLUDE` filters it out, then a final pass aborts if any `src/` path survived.
+- **Secret-scan refuses on any finding.** `publish-public.mjs` blocks on the **first** match per file across 10 inline patterns + a sensitive-filename rule. It is deliberately conservative (`512 KB` text-file cap, placeholder-credential allowance to avoid false positives in docs).
+- **`.env` and DB files are sensitive by filename.** They are blocked even if you never opened them — except the explicit allowlist (`.env.example`, etc.) and `drizzle/*.sql` DDL.
+- **Force-push is intentional.** The public repo is a *clean mirror*, not a collaboration history. It carries no `.next` and no secrets, so overwriting it is safe by construction.
+- **The tarball is compiled.** End users run a minified `.next` and applied SQL migrations — no readable application source, no devDependencies.
+- **Secrets live outside the tree.** Runtime secrets are persisted to `<HOME>/.env` (`chmod 600`) and never in the repo; the vault key, worker secret and auth secret are generated at first boot. See [SECURITY](./SECURITY.md).
+
+> The scanner is a safety net, not a substitute for discipline. Keep secrets in `<HOME>/.env` and the vault, never in tracked files.
+
+---
+
+## Troubleshooting 🛰️
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `Refusing to publish — N finding(s)` | A tracked/`drizzle` file matched a secret or sensitive-filename rule | Inspect each listed path; redact, remove from the publish set, or (for legit cases) confirm it fits an allow rule. Re-run the dry run. |
+| `src/ leaked into the public tree` | A path under `src/` reached the publish set | This should be impossible via `EXCLUDE`; verify nothing force-adds `src/` and re-run. |
+| `npm publish` aborts immediately | `package.json` has `"private": true` | Flip/remove `private` once the npm account exists (per the `//private` note). |
+| `trim-next: no .next/ — nothing to trim` then a broken tarball | No build before packing | Run `npm run build` (or rely on `prepublishOnly`, which builds) before `npm pack`. |
+| Public push fails on an empty remote | Pushing a bare commit to `main` can't infer the ref | Already handled — the script pushes `<commit>:refs/heads/main` explicitly. |
+| `git push -f public …` rejected | `public` remote missing or unauthenticated | `git remote add public https://github.com/gabriel7silva/constella.git`; ensure credentials/`GIT_TERMINAL_PROMPT` allow non-interactive auth. |
+| Migrations missing in the mirror | `drizzle/` was empty and generate failed | Run `npm run db:generate` manually and inspect the error before re-running. |
+| EN/PT parity failure during `validate` | A dictionary key exists in one language only | Fix `src/lib/i18n.ts` so EN ↔ PT keys match; see [CONFIGURATION](./CONFIGURATION.md). |
+
+---
+
+## Related links
+
+- [INSTALLATION](./INSTALLATION.md) — what an end user actually receives and where it lands.
+- [UPDATE](./UPDATE.md) — how users pull new published versions.
+- [SECURITY](./SECURITY.md) — the vault, the FS jail, and the secret-scanning engine.
+- [GITHUB](./GITHUB.md) — the commit/export path that shares the secret scanner.
+- [PREPARE_DEPLOY](./PREPARE_DEPLOY.md) · [DEPLOY](./DEPLOY.md) — shipping a *built product*, distinct from publishing Constella itself.
+- [CONFIGURATION](./CONFIGURATION.md) — i18n parity and the validate gate.
+- [ARCHITECTURE](./ARCHITECTURE.md) — the runtime root and the dir-is-truth model.
+
+---
+
+<sub>✦ The shipyard is quiet, the launch is loud. Ship the product, keep the blueprints. 🚀</sub>