Merge pull request #110 from jsilvanus/claude/whatnext-planning-n0bndq

Design + schedule: multi-tenant auth, public-repo sharing, locked model sets

Author: jsilvanus

docs/PLAN.md

@@ -4691,6 +4691,67 @@ that deprecated it, and its removal status.
 
 ---
 
+## Multi-Tenant Auth Track (Phases 122–125)
+
+> **Full design:** [`docs/multi-tenant-auth-plan.md`](multi-tenant-auth-plan.md)
+> is the single design reference for this track (current-state assessment,
+> the identity/membership/grant axis model, personal groups, and Phases
+> A–D). Phase A has no dependents blocking it; Phase B hard-depends on
+> Phase A; Phase C depends only on Phase A; Phase D can slip independently
+> of all three. Phase entries below use the next free top-level phase
+> numbers after 121.
+
+| Phase | Spec section | Title | Deliverable |
+|---|---|---|---|
+| **122** | §5 Phase A | Identity & credentials core | New `users`/`sessions`/`api_keys` tables; `POST /api/v1/auth/login`/`logout`/`tokens` routes; `authMiddleware` extended to try user-credential resolution first, falling back to today's legacy `GITSEMA_SERVE_KEY`/`repo_tokens` path; CLI `gitsema auth login/logout/token */whoami`. No authorization changes yet — identity only. |
+| **123** | §5 Phase B | Orgs, personal groups, repo/branch grants, self-service | New `orgs` (`kind: personal\|team`)/`org_members`/`repo_grants` tables; nullable `repos.org_id`; `auth.personalGroups`/`GITSEMA_PERSONAL_GROUPS` config gate (default `true`) auto-provisioning a one-member personal org per new user; `gitsema repos move-to-org`; branch-pattern grants requiring `branch: string` → `string \| string[]` across ~16 routes; CLI `gitsema orgs */repos grant/grants list/revoke/move-to-org`, `gitsema users create/list`; `docs/deprecations.md` row for `repo_tokens`. |
+| **124** | §5 Phase C | SSO/OIDC linking | New `sso_identities` table; `gitsema auth login <server-url> --sso <provider>` device-code-style flow; provider allowlist config; first new third-party dependency (an OIDC client library) — flagged against CLAUDE.md's minimal-deps preference. |
+| **125** | §5 Phase D | Audit log | New `audit_log` table (actor, action, target, timestamp); `gitsema audit log [--org][--repo]` CLI; records `org.repo.moved` and other Phase B/C actions. Lowest priority of the track, no hard dependents. |
+
+**Status:** not started — draft design, scheduled here per `/phase-plan`.
+
+---
+
+## Public Repo Sharing Track (Phases 126–127)
+
+> **Full design:** [`docs/public-repo-sharing-plan.md`](public-repo-sharing-plan.md)
+> is the single design reference for this track (visibility flag,
+> attach-as-reader auto-grants, first-index gate, refresh throttle). Both
+> phases hard-depend on the Multi-Tenant Auth Track's Phase A (122) and
+> Phase B (123) landing first — there is no `users`/`repo_grants` model to
+> attach a reader grant to otherwise.
+
+| Phase | Spec section | Title | Deliverable |
+|---|---|---|---|
+| **126** | §5 Phase 1 | Visibility flag + attach-as-reader | `repos.visibility` (`'private'\|'public'`, default `'private'`) + `ownerUserId` columns; `gitsema repos visibility <repoId> public\|private` CLI (owner/superadmin only); registration-flow change in `src/server/routes/remote.ts` auto-issuing a `repo_grants` reader row when a second user attaches to an existing public repo's shared index. |
+| **127** | §5 Phase 2 | First-index gate + refresh throttle | `auth.allowPublicAutoIndex`/`GITSEMA_PUBLIC_AUTO_INDEX` config gate (default `false`) restricting who may register a brand-new public-flagged repo; `auth.minReindexIntervalSeconds` per-`(user, repoId)` refresh throttle returning `429`/`Retry-After`. No hard dependency on Phase 126 beyond the `visibility` column existing. |
+
+**Status:** not started — draft design, scheduled here per `/phase-plan`.
+Explicitly out of scope (per the design doc §6): cross-repo blob-level dedup
+for forks with different URLs ("shape 2") remains undesigned and unscheduled.
+
+---
+
+## Superadmin-Locked Model Set Track (Phases 128–130)
+
+> **Full design:** [`docs/locked-model-set-plan.md`](locked-model-set-plan.md)
+> is the single design reference for this track (multi-profile embedding
+> serving, admin-gated enabled sets, never-persisted per-request BYOK).
+> Phase 128 has no hard dependency on the role model and could ship before
+> the Multi-Tenant Auth Track lands; Phase 129 hard-depends on that track's
+> Phase A (122) and Phase B (123); Phase 130 has no hard dependency on
+> Phase 128 but benefits from Phase 129's allow-list existing.
+
+| Phase | Spec section | Title | Deliverable |
+|---|---|---|---|
+| **128** | §5 Phase 1 | Multi-profile embedding serving | Server config shape for N named embedding profiles; `gitsema tools serve` builds a `Map<profileName, {textProvider, codeProvider}>` instead of one global pair; `repos.profileName` column pinned at first index and immutable after; CLI `gitsema index start --profile <name>`, `gitsema repos info` surfacing the pinned profile. |
+| **129** | §5 Phase 2 | Admin-gated enabled sets | Superadmin admin CLI/route enabling/disabling defined profiles and narrator/guide configs server-wide; org-level narrowing (never widening) reusing the Multi-Tenant Auth Track's org/role model; picker UX (pre-selected/disabled when exactly one profile is allowed, real picker otherwise). |
+| **130** | §5 Phase 3 | BYOK for narrator/guide | Request-scoped credential field on `narrate`/`explain`/`guide` CLI/HTTP/MCP entry points; one-off provider construction via `createNarratorProviderFor()` with no persistence path; "lock to none" support (empty allow-list as a valid, tested state). |
+
+**Status:** not started — draft design, scheduled here per `/phase-plan`.
+
+---
+
 ## Deployment scenarios & usage envisioning
 
 The architecture of gitsema supports three distinct deployment scenarios, each with different operational models and target users. This section clarifies the intended usage patterns and the infrastructure requirements for each.

docs/feature-ideas.md

@@ -2,7 +2,7 @@
 
 This document tracks upcoming feature ideas that are **not yet in active development** (not in `PLAN.md`) and haven't been **fully designed** (no design file). It's a staging area for "what now?" questions and medium-term product direction.
 
-**Last updated:** 2026-06-22
+**Last updated:** 2026-06-22 (refined public-repo sharing's access-control half into `docs/public-repo-sharing-plan.md` and the superadmin-locked model set idea into `docs/locked-model-set-plan.md`; kept cross-repo blob dedup as an open idea)
 **Audience:** Developers considering next phases; product planning
 
 > **Note:** As of this update, the LSP/MCP remote-delegation foundation this
@@ -156,25 +156,30 @@ A **managed platform** built on top of the self-hosted remote MCP foundation:
 
 ### Design Gaps
 
-- [ ] `gitsema auth login`/`logout`/`token` commands (currently no `auth` command group — tokens are managed via `gitsema config set`/repo tokens today)
-- [ ] How are user credentials stored locally? (keychain integration?)
-- [ ] Token expiration & refresh flow?
-- [ ] What's the max index size per user tier?
-- [ ] Rate limits (queries/sec, indexing jobs/month)?
-- [ ] Team sharing (shared indexes, collaborative access)?
-- [ ] Audit logging (who indexed what, when)?
-- [ ] SLA and uptime guarantees?
-- [ ] Data residency (GDPR compliance)?
+> **Refined into:** the gitsema-side identity/auth/access-control work
+> (user accounts, `gitsema auth login/logout/token`, per-user per-repo
+> per-branch grants, org-scoped self-service, SSO linking) has been promoted
+> to its own design document: **[`docs/multi-tenant-auth-plan.md`](multi-tenant-auth-plan.md)**.
+> The gaps below are kept for history; see that doc for resolved answers and
+> the remaining genuinely-open questions.
+
+- [x] `gitsema auth login`/`logout`/`token` commands — see `multi-tenant-auth-plan.md` §4.3, §5 Phase A.
+- [x] How are user credentials stored locally? — see `multi-tenant-auth-plan.md` §4.1 (follows the existing `config.json` plaintext-secret precedent, `~/.config/gitsema/credentials.json`, 0o600).
+- [x] Token expiration & refresh flow? — see `multi-tenant-auth-plan.md` §4.1 (sessions expire, API keys don't by default, `--expires` opt-in).
+- [x] Team sharing (shared indexes, collaborative access)? — see `multi-tenant-auth-plan.md` §4.2 (orgs, per-repo/per-branch `repo_grants`, org-scoped self-service).
+- [ ] What's the max index size per user tier? — still open; Semahub Layer-2 (billing/quota) territory, not gitsema-side.
+- [ ] Rate limits (queries/sec, indexing jobs/month)? — still open; per-user/org quotas explicitly out of scope for `multi-tenant-auth-plan.md` Phases A–D (see its §6), deferred to Semahub Layer 2.
+- [ ] Audit logging (who indexed what, when)? — partially addressed: `multi-tenant-auth-plan.md` §5 Phase D scopes a gitsema-side `audit_log` table, but it's the lowest-priority phase and may slip.
+- [ ] SLA and uptime guarantees? — still open; Semahub Layer-2.
+- [ ] Data residency (GDPR compliance)? — still open; Semahub Layer-2.
 
 ### MVP Scope
 
 Start small:
 1. **Phase A (Semahub):** User signup, index storage, job queue
-2. **Phase B (gitsema, small):** `gitsema auth login/logout/token` convenience commands wrapping existing config/token plumbing
+2. **Phase B (gitsema):** see `docs/multi-tenant-auth-plan.md` for the now-fully-designed phased plan (Phases A–D there, ~1850–2550 LOC total) — supersedes the placeholder estimate that used to be here.
 3. **Phase C (Semahub):** Web dashboard, billing
 
-**Total effort:** Semahub: 6-10 weeks (gitsema-side work is now minimal — a thin `auth` command group, ~200-300 LOC)
-
 ### Competitive Advantages
 
 - **Integrated IDE experience:** CLI, LSP, MCP all work seamlessly
@@ -244,6 +249,156 @@ a language-specific structural extractor, or an org-specific compliance scan.
 
 ---
 
+## Shared/Deduplicated Indexing for Public Repos
+
+> **Refined into:** the access-control half of this idea (a `visibility`
+> flag, auto-granted read access when a user attaches to an existing public
+> repo, and abuse-resistant gating of first-index vs. refresh) has been
+> promoted to its own design document:
+> **[`docs/public-repo-sharing-plan.md`](public-repo-sharing-plan.md)**.
+> That doc's research also found that the storage/clone-duplication concern
+> this idea originally worried about is **already solved** today —
+> `src/core/indexing/repoRegistry.ts` already dedupes registrations by
+> normalized URL onto one clone/index DB, and re-indexing an unchanged repo
+> is already cheap (incremental + blob-hash dedup). See that doc's §2 for
+> the full citations.
+
+The second, looser shape below — cross-repo blob-level dedup for forks with
+*different* URLs — was explicitly kept **out of scope** for that design (it's
+architecturally a much bigger lift) and remains here as a genuinely
+undesigned idea:
+
+### Remaining open idea: partial index reuse / blob-level sharing across forks
+Even for different URLs (e.g. a fork), recognize when blobs are
+byte-identical (same blob hash — already how gitsema dedupes *within* one
+repo) and skip re-embedding those blobs server-wide, only embedding the
+genuinely new/changed blobs introduced by the fork.
+
+- [ ] Requires re-scoping `blobs`/`embeddings` storage to be content-
+      addressed *globally* rather than per-repo-DB file, cutting across the
+      storage-backend abstraction (`src/core/storage/types.ts`) and every
+      backend (sqlite/postgres/qdrant).
+- [ ] Needs a cross-repo identity for a blob beyond what one index DB knows
+      — either a shared blob registry + per-repo lookup tables, or a
+      sync/copy mechanism between DBs.
+- [ ] Interacts with whatever visibility/grant model
+      `public-repo-sharing-plan.md` ships — sharing blobs across two
+      *different* repos' indexes raises the same "who's allowed to read
+      what" questions as that doc, just one level deeper (blob-level instead
+      of repo-level).
+
+### Effort Estimate
+- Substantial — comparable in size to the storage-backends work itself
+  (multi-phase). Not estimated further until shape-1's access-control layer
+  (`public-repo-sharing-plan.md`) ships and proves out the simpler case.
+
+### Prerequisites
+- `docs/public-repo-sharing-plan.md` landing first (the visibility/grant
+  model this would need to extend), and likely `multi-tenant-auth-plan.md`
+  before that.
+
+---
+
+## Superadmin-Locked Model Set (Server-Side Model Allowlist)
+
+> **Refined into:** **[`docs/locked-model-set-plan.md`](locked-model-set-plan.md)**.
+> That doc's research found that the embedding half of this idea needed a
+> genuinely new capability — a multi-tenant server has only ever had a
+> single, process-wide embedding model with no per-request override, so
+> "locking" it was previously a no-op; the design adds multi-profile serving
+> first, then admin/org-level enabled-set control on top. The narrator/guide
+> half was already multi-model today and just needed admin-gating + a
+> never-persisted BYOK path, both designed in that doc. The gaps below are
+> kept for history; see that doc for resolved answers and remaining open
+> questions.
+
+### Problem
+- On a shared/multi-tenant server (`gitsema tools serve`), nothing today
+  stops a user from indexing or querying with whatever
+  `GITSEMA_MODEL`/`GITSEMA_TEXT_MODEL`/`GITSEMA_CODE_MODEL` they pass —
+  there's no concept of an operator-controlled allowed set.
+- This matters most for **embedding models**: vectors from two different
+  embedding models aren't comparable, so if a shared index's vectors mix
+  models, search silently degrades or breaks. A server operator needs to be
+  able to pin the server to one (or a small vetted few) embedding model(s)
+  so every repo's index stays internally consistent.
+- It also applies to narrator/guide chat models (used by `narrate`/`explain`/
+  `guide`), though the motivation there is different (cost/quality/abuse
+  control of LLM calls) rather than vector compatibility.
+- There's currently no "superadmin" role concept at all in gitsema — today's
+  server auth is a single global `GITSEMA_SERVE_KEY` plus per-repo
+  `repo_tokens` (see `docs/multi-tenant-auth-plan.md` for the in-progress
+  identity/role model this idea would need to sit on top of).
+
+### Intended Behavior
+A server superadmin configures an **allowed model set** — separately for
+embedding models and for narrator/guide models — via a new admin CLI/API
+(not just a config file edit, per the answered design question, since this
+needs to be a controlled, auditable admin action once roles exist). Regular
+users:
+- When the allowed set has exactly one model, see it as a **pre-selected,
+  disabled** choice (not an editable picker) wherever a model would
+  otherwise be selectable (`index start --model`, `gitsema config set
+  model`, etc.) — they always see *which* model is active, they just can't
+  change it.
+- When the allowed set has more than one model, get a real picker limited to
+  that set.
+- Can still **bring their own API key (BYOK)** to use a model of their own
+  choosing for narrator/guide chat, even when the server's own default
+  narrator/guide model is locked or disabled entirely ("lock to none" is an
+  explicit valid server posture for chat — i.e. no server-provided chat
+  model at all, BYOK-only). BYOK does not apply to embedding models, since
+  BYOK embeddings would reintroduce the vector-incompatibility problem this
+  idea exists to prevent.
+- Per the answered design question, the allowed set is **global by default**
+  (set by the superadmin for the whole server) but an **org_admin may
+  further narrow** (never widen) the set for their own org — layering on top
+  of `docs/multi-tenant-auth-plan.md`'s org/role model rather than
+  introducing a second, separate permission system.
+
+### Design Gaps
+- [ ] The "superadmin" role doesn't exist yet — does it ride on top of
+      `multi-tenant-auth-plan.md`'s eventual `org_admin`/user roles as a new
+      server-wide role, or is it a separate concept (e.g. tied to whoever
+      holds `GITSEMA_SERVE_KEY` today)? This idea is blocked on that role
+      existing in some form.
+- [ ] Exact shape of the new admin CLI/API: `gitsema admin models allow
+      <model> [--kind embedding|narrator]` / `gitsema admin models deny
+      <model>`? An HTTP route under `/api/v1/admin/...`? Both?
+- [ ] What happens to a repo's *existing* index if the superadmin later
+      removes its embedding model from the allowed set — does search just
+      stop working for that repo (data still there, queries rejected), or
+      does it force a re-index banner/block?
+- [ ] How does org-level narrowing interact with personal groups
+      (`multi-tenant-auth-plan.md` §4.2a) — does a personal group count as
+      an "org" for this purpose, or do personal-group users always inherit
+      the server-wide set unmodified?
+- [ ] Where does the "pre-selected, disabled" single-model UX surface
+      outside the CLI — does the (currently nonexistent) Semahub web
+      dashboard need this too, or is this purely a CLI/HTTP-API-level
+      concern for now?
+- [ ] BYOK credential storage/handling for narrator/guide: does the user's
+      own API key get stored server-side (raising the same plaintext-secret
+      precedent question as `multi-tenant-auth-plan.md` §4.1), or is it
+      supplied per-request only and never persisted?
+
+### Effort Estimate
+- Depends heavily on the role-model prerequisite landing first. Once a
+  role/permission system exists (per `multi-tenant-auth-plan.md`), this is a
+  moderate addition: a new allowlist concept (global + org-level override),
+  admin CLI/routes to manage it, and enforcement points at every model-
+  selection site (`index start`, `config set model/textModel/codeModel`,
+  narrator/guide model activation). Rough order: 500-800 LOC, mostly
+  enforcement-point plumbing rather than novel architecture.
+
+### Prerequisites
+- Needs a superadmin/role concept to exist — directly depends on
+  `docs/multi-tenant-auth-plan.md` landing (at least Phase A's user/session
+  model, likely Phase B's org/role model for the org-level narrowing
+  behavior). Not actionable before that.
+
+---
+
 ## Related Issues & Documents
 
 - **Parity tracking:** See `docs/parity.md` for tool availability across interfaces