docs: instance branches should be orphan branches

Records why, so the next person doesn't rebuild the trap: a branch off main
carries a full copy of the app it has no reason to have and drifts behind it,
and syncing it via `git merge origin/main` silently replaces the instance
manifests with main's placeholders — no conflict, because only main touches
those paths.

instance/dnspegasus has been converted accordingly.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "cybercove-labs",
+  "description": "Open-source Claude Code plugins released by CyberCove Labs.",
+  "owner": {
+    "name": "CyberCove Labs",
+    "url": "https://repo.anhonesthost.net/cybercove-labs/shared-memory"
+  },
+  "plugins": [
+    {
+      "name": "shared-memory",
+      "source": "./plugin",
+      "description": "Shared persistent memory and snippet library for Claude Code sessions, backed by your own shared-memory server and authenticated with OIDC."
+    }
+  ]
+}

.env.example

@@ -31,11 +31,28 @@ ACME_EMAIL=you@example.com
 # resource server). See README.md for exact provider settings.
 # -----------------------------------------------------------------------------
 OIDC_ISSUER=https://auth.example.com/application/o/shared-memory/
+# Issuer of MCP access tokens, when the MCP endpoint is a separate application
+# in your IdP (it usually is). Authentik stamps each token with its own app
+# slug, so verifying MCP tokens against OIDC_ISSUER fails with
+# "claim invalid: iss". Defaults to OIDC_ISSUER.
+OIDC_ISSUER_MCP=https://auth.example.com/application/o/shared-memory-mcp/
 OIDC_CLIENT_ID_WEB=replace-me
 OIDC_CLIENT_SECRET_WEB=replace-me
 OIDC_CLIENT_ID_MCP=replace-me
 OIDC_AUDIENCE=shared-memory
 
+# Marketplace this instance's Claude Code plugin is published from. When set,
+# the CLI tokens page shows the one-command plugin install so people only mint
+# a bearer token when a browser sign-in genuinely isn't possible.
+#PLUGIN_MARKETPLACE_URL=https://your-git-host/you/shared-memory.git
+#PLUGIN_MARKETPLACE_NAME=shared-memory
+# Scope whose IdP mapping emits `aud: <OIDC_AUDIENCE>`. Advertised in
+# /.well-known/oauth-protected-resource so MCP clients request it — without
+# that, Authentik never evaluates the mapping and every token 401s with
+# "claim invalid: aud". Defaults to aud-<OIDC_AUDIENCE>; set only if you
+# named the scope mapping something else.
+#OIDC_AUDIENCE_SCOPE=aud-shared-memory
+
 # -----------------------------------------------------------------------------
 # Database (Postgres 16 + pgvector — pgvector/pgvector:pg16 image)
 # -----------------------------------------------------------------------------

CLAUDE.md

@@ -0,0 +1,25 @@
+# CLAUDE.md — shared-memory
+
+Project key (for the shared-memory MCP): `shared-memory` (set by the `.shared-memory-project` marker at the repo root).
+
+## Consulting memory before substantive work
+
+There are TWO memory stores. The file-based memory (`MEMORY.md` + topic files) is auto-loaded into context every session. The **shared-memory MCP** (`mcp__shared-memory__*`) is NOT auto-loaded — you must query it. Query on demand when you need detail; do not bulk-load everything (that wastes context).
+
+When a request draws on accumulated project knowledge — an architecture/development overview, debugging, planning, reviewing, or implementing a feature, or any question about how the system works — do this BEFORE answering or acting:
+
+1. Use what's already in the auto-loaded `MEMORY.md` index.
+2. ALSO check the shared-memory MCP: call `project_identify` once per session (resolves the key from `.shared-memory-project`), then `memory_search` with the task topic in natural language (a couple of queries if the task spans areas). Fetch full bodies with `memory_get` when a hit looks relevant.
+3. Fold both sources into your answer; note when something came from saved memory.
+
+## Reusing saved snippets (boilerplate / templates) before recreating work
+
+Snippets (`mcp__shared-memory__snippet_*`) hold reusable artifacts — boilerplate, standard formats, checklists, established workflows. They are pull-only and, unlike memory, **NOT searchable**: `snippet_get` fetches by EXACT name, and the `description` shown by `snippet_list` is the ONLY discovery surface (tags are just for human browsing).
+
+Before hand-writing standard/boilerplate code or re-deriving a known workflow, check whether a template already exists:
+
+1. Call `snippet_list` once — it's cheap: it returns names + descriptions + tags, **no bodies**. Scan the descriptions for a match.
+2. If one fits, `snippet_get <name>` to pull just that body and apply it, instead of recreating it from scratch.
+3. When you produce a reusable artifact worth keeping, save it with `snippet_put` under a stable, predictable name (e.g. `boilerplate/<area>/<thing>`) and a concrete "when to use" `description` so a future agent can find it by scanning `snippet_list`.
+
+Skip both checks only for trivial, self-contained requests (a quick edit, a one-off shell command, casual conversation) where prior project context can't matter. If the MCP server isn't connected in this session, proceed with file memory and say so.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Josh Knapp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -144,6 +144,10 @@ Copy `.env.example` and fill in the values below.
 | `OIDC_CLIENT_SECRET_WEB` | both | Client secret of the Web-UI client. |
 | `OIDC_CLIENT_ID_MCP` | both | Client ID of the MCP resource-server client in your IdP. |
 | `OIDC_AUDIENCE` | both | Audience string the MCP access token must carry in its `aud` claim. Recommended: `shared-memory`. |
+| `OIDC_ISSUER_MCP` | optional | Issuer of MCP access tokens when the MCP endpoint is a separate IdP application (Authentik stamps each app's tokens with its own slug). Defaults to `OIDC_ISSUER`. |
+| `PLUGIN_MARKETPLACE_URL` | optional | Marketplace URL for this instance's plugin. Shown as a one-command install on the CLI tokens page. Hidden when unset. |
+| `PLUGIN_MARKETPLACE_NAME` | optional | Marketplace name used in `shared-memory@<name>`. Defaults to `shared-memory`. |
+| `OIDC_AUDIENCE_SCOPE` | optional | Name of the IdP scope whose mapping emits that `aud` claim. Advertised in `scopes_supported` so clients request it. Defaults to `aud-<OIDC_AUDIENCE>`. |
 | `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` | both | Local Postgres credentials. |
 | `NEXTAUTH_SECRET` | both | Session-cookie signing key. Generate with `openssl rand -base64 32`. |
 | `EMBEDDER_URL` | both | Phase 2 embedder sidecar. Leave empty in Phase 1. |
@@ -297,16 +301,52 @@ The MCP endpoint requires the access token's `aud` claim to equal
 reliable pattern:
 
 1. Create a **scope mapping** (Customisation → Property Mappings → Create →
-   Scope Mapping) named `aud-shared-memory` with expression:
+   Scope Mapping) named `aud-shared-memory`, **scope name** `aud-shared-memory`,
+   with expression:
    ```python
    return {"aud": "shared-memory"}
    ```
-2. On the MCP provider, add this scope mapping under **Scopes** and tick it
+2. On the MCP provider, add this scope mapping under **Scopes**.
-   so it's emitted for the default scope.
+3. Make sure the app advertises that scope name. It is derived automatically
+   as `aud-<OIDC_AUDIENCE>`; override with `OIDC_AUDIENCE_SCOPE` if you named
+   the mapping differently.
 
-> If you skip this, the MCP route will return 401 with
+> **Attaching the mapping is not sufficient.** Authentik evaluates a scope
-> `error_description="claim invalid: aud"`. Check `docker compose logs app`
+> mapping only when the client explicitly *requests* that scope, and an MCP
-> for the exact failure.
+> client only requests the scopes listed in `scopes_supported` from
+> `/.well-known/oauth-protected-resource`. If the audience scope isn't
+> advertised there, the mapping silently never runs, the access token carries
+> no `aud`, and every MCP call fails with 401
+> `error_description="claim invalid: aud"` — even though the OAuth handshake,
+> consent, and PKCE all succeeded. Verify with:
+>
+> ```bash
+> curl -s https://memory.example.com/.well-known/oauth-protected-resource \
+>   | jq .scopes_supported     # must include aud-<your audience>
+> ```
+>
+> **Second trap, same failure surface:** the MCP endpoint is a *separate
+> application* from the Web UI, and Authentik's default `per_provider` issuer
+> mode stamps each token with its own application slug. So MCP tokens carry
+> `iss: .../application/o/shared-memory-mcp/` while `OIDC_ISSUER` points at
+> `.../application/o/shared-memory/`, and verification fails with
+> `claim invalid: iss` even once `aud` is correct. Set `OIDC_ISSUER_MCP` to the
+> MCP application's issuer. Confirm which one your tokens actually carry:
+>
+> ```bash
+> curl -s https://auth.example.com/application/o/shared-memory-mcp/.well-known/openid-configuration | jq .issuer
+> ```
+>
+> **Identity note:** the app verifies MCP tokens against `OIDC_ISSUER_MCP` but
+> keys the user record on `OIDC_ISSUER`. Authentik's `sub` is `user.uid`, which
+> is stable across providers, so the same person resolves to the same row
+> whether they arrive via the Web UI or the MCP endpoint. Without that
+> normalization the MCP path silently creates a second, empty account instead
+> of failing visibly.
+>
+> Note also that Claude Code sends an RFC 8707 `resource` parameter on the
+> authorize request; Authentik 2026.5 ignores it, so it cannot be relied on
+> for audience binding. The scope mapping is what sets `aud`.
 
 Then create an **Application** for the MCP provider (same as Step A), slug
 e.g. `shared-memory-mcp`.
@@ -322,9 +362,74 @@ prompt, never reaching the app.
 
 ## Connecting Claude Code
 
-Two paths, in order of preference:
+Three paths, in order of preference:
 
-### A. OAuth flow (recommended — picks up your IdP credentials)
+### A. Plugin (recommended — one command, no flags to remember)
+
+This repo doubles as a Claude Code plugin marketplace. `plugin/.mcp.json` ships a
+**pre-registered** OAuth client, so Claude Code never needs RFC 7591 Dynamic Client
+Registration — which matters because most self-hosted IdPs (Authentik included, as of
+2026.5) don't implement it.
+
+`main` carries placeholders, so install from `main` only after pointing it at your own
+instance. Fork or clone, then edit `plugin/.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "shared-memory": {
+      "type": "http",
+      "url": "https://memory.example.com/api/mcp",
+      "oauth": {
+        "clientId": "<OIDC_CLIENT_ID_MCP>",
+        "callbackPort": 33418
+      }
+    }
+  }
+}
+```
+
+`clientId` is the **Public** (PKCE) client from step B above — it is not a secret and is
+meant to be committed. `callbackPort` must match a redirect URI your IdP accepts; with
+the loopback regex from the setup step, any port works.
+
+Then:
+
+```bash
+claude plugin marketplace add https://your-git-host/you/shared-memory.git
+claude plugin install shared-memory@cybercove-labs
+```
+
+To keep a filled-in copy on a branch instead of forking, commit it to e.g.
+`instance/<name>` and install with a `#ref` fragment:
+
+```bash
+claude plugin marketplace add https://your-git-host/you/shared-memory.git#instance/<name>
+```
+
+The `#ref` suffix is undocumented in `claude plugin marketplace add --help` but is
+honored and persisted in `known_marketplaces.json` (verified on Claude Code 2.1.220).
+
+**Make that an orphan branch, not a branch off `main`.** `marketplace add` reads
+only the manifests, so the branch needs nothing else:
+
+```bash
+git checkout --orphan instance/<name>
+git rm -rf --cached . && find . -mindepth 1 -maxdepth 1 ! -name .git -exec rm -rf {} +
+# restore just .claude-plugin/marketplace.json, plugin/.claude-plugin/plugin.json,
+# plugin/.mcp.json — fill in your URL and client ID
+claude plugin validate . && git add -A && git commit && git push
+```
+
+A branch off `main` carries a full copy of the application it has no reason to
+have, so it drifts and someone can cut a stale deploy from it. Worse, syncing it
+means `git merge origin/main`, which **silently replaces those manifests** with
+the placeholders below — no conflict is raised, because only `main` ever touches
+those paths. With no shared history there is nothing to sync and nothing to
+clobber; if the manifest format changes upstream, hand-edit the three files and
+re-run `claude plugin validate .`.
+
+### B. OAuth flow (manual, per-machine)
 
 ```bash
 claude mcp add --transport http --scope user \
@@ -350,7 +455,7 @@ your MCP client's **Redirect URIs** list. Authentik users with the regex
 pattern from the setup step (`^http://(127\.0\.0\.1|localhost):\d+/.*$`)
 can use any port without re-registering.
 
-### B. Manual-paste fallback (when loopback isn't reachable)
+### C. Manual-paste fallback (when loopback isn't reachable)
 
 Sealed containers, devboxes without port forwarding, etc. The redirect URI
 in this case is hosted by *this* server:
@@ -372,7 +477,7 @@ Claude Code's prompt to complete the flow.
 The manual-fallback URI must be registered on your MCP client too:
 `https://memory.example.com/auth/cli-callback`.
 
-### C. Static bearer token (no browser at all)
+### D. Static bearer token (no browser at all)
 
 For fully headless / CI scenarios, mint a long-lived HMAC token at
 `https://memory.example.com/connect` and pass it via `--header`. See

apps/web/app/(authed)/memories/_project-combobox.tsx

@@ -0,0 +1,151 @@
+"use client";
+
+import { useEffect, useId, useRef, useState } from "react";
+
+const field =
+  "block w-full rounded-md bg-surface-1 border border-border " +
+  "text-fg placeholder:text-fg-subtle " +
+  "focus:border-accent-400 focus:outline-none " +
+  "disabled:opacity-50 transition-colors h-9 px-3 text-sm";
+
+/**
+ * Type-ahead project filter. A text input whose value submits as `name`
+ * (default "project") via the enclosing GET form, plus a dropdown of the
+ * projects the user can read that narrows as they type. Selecting a
+ * suggestion fills the box and submits the form so the filter applies
+ * immediately; free text is still allowed (the input value is what
+ * submits), so an arbitrary key keeps working even if it isn't listed.
+ */
+export function ProjectCombobox({
+  name = "project",
+  defaultValue = "",
+  options,
+  className = "",
+}: {
+  name?: string;
+  defaultValue?: string;
+  options: string[];
+  className?: string;
+}) {
+  const [value, setValue] = useState(defaultValue);
+  const [open, setOpen] = useState(false);
+  const [active, setActive] = useState(0);
+  const rootRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const listId = useId();
+
+  // Case-insensitive substring match. An empty box shows the full list so
+  // the control doubles as a "browse my projects" dropdown.
+  const q = value.trim().toLowerCase();
+  const matches = q
+    ? options.filter((o) => o.toLowerCase().includes(q))
+    : options;
+
+  // Close when focus/click leaves the widget.
+  useEffect(() => {
+    if (!open) return;
+    function onPointerDown(e: PointerEvent) {
+      if (!rootRef.current?.contains(e.target as Node)) setOpen(false);
+    }
+    document.addEventListener("pointerdown", onPointerDown);
+    return () => document.removeEventListener("pointerdown", onPointerDown);
+  }, [open]);
+
+  function commit(next: string) {
+    setValue(next);
+    setOpen(false);
+    // Write the DOM value synchronously before submitting: setValue only
+    // schedules a re-render (React batches it), so the input's serialized
+    // value would still be the pre-selection text when requestSubmit reads
+    // it. The upcoming render sets the same value, so there's no flicker.
+    if (inputRef.current) inputRef.current.value = next;
+    // requestSubmit fires a real submit (unlike form.submit()).
+    inputRef.current?.form?.requestSubmit();
+  }
+
+  function onKeyDown(e: React.KeyboardEvent<HTMLInputElement>) {
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      if (!open) {
+        setOpen(true);
+        setActive(0);
+      } else {
+        setActive((i) => Math.min(i + 1, matches.length - 1));
+      }
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      setActive((i) => Math.max(i - 1, 0));
+    } else if (e.key === "Enter") {
+      // Only intercept Enter to pick a highlighted suggestion; otherwise
+      // let it fall through and submit the form with the typed value.
+      if (open && matches[active]) {
+        e.preventDefault();
+        commit(matches[active]);
+      }
+    } else if (e.key === "Escape") {
+      if (open) {
+        e.preventDefault();
+        setOpen(false);
+      }
+    }
+  }
+
+  const showList = open && matches.length > 0;
+
+  return (
+    <div ref={rootRef} className={`relative ${className}`}>
+      <input
+        ref={inputRef}
+        type="text"
+        name={name}
+        value={value}
+        placeholder="Project key…"
+        autoComplete="off"
+        spellCheck={false}
+        role="combobox"
+        aria-expanded={showList}
+        aria-controls={listId}
+        aria-autocomplete="list"
+        aria-activedescendant={
+          showList ? `${listId}-opt-${active}` : undefined
+        }
+        className={field}
+        onChange={(e) => {
+          setValue(e.target.value);
+          setOpen(true);
+          setActive(0);
+        }}
+        onFocus={() => setOpen(true)}
+        onKeyDown={onKeyDown}
+      />
+      {showList ? (
+        <ul
+          id={listId}
+          role="listbox"
+          className="absolute z-20 mt-1 max-h-60 w-full overflow-auto rounded-md border border-border bg-surface-1 py-1 shadow-lg"
+        >
+          {matches.map((opt, i) => (
+            <li
+              key={opt}
+              id={`${listId}-opt-${i}`}
+              role="option"
+              aria-selected={i === active}
+              className={`cursor-pointer px-3 py-1.5 font-mono text-sm text-fg ${
+                i === active ? "bg-surface-2" : ""
+              }`}
+              // pointerdown (not click) so the choice registers before the
+              // input's blur/outside-pointerdown handler closes the list.
+              onPointerDown={(e) => {
+                e.preventDefault();
+                commit(opt);
+              }}
+              onMouseEnter={() => setActive(i)}
+            >
+              {opt}
+            </li>
+          ))}
+        </ul>
+      ) : null}
+    </div>
+  );
+}

apps/web/app/(authed)/memories/page.tsx

@@ -1,10 +1,15 @@
 import Link from "next/link";
-import { and, desc, eq, isNull, inArray, or, sql } from "drizzle-orm";
+import { and, desc, eq, isNull, inArray, or } from "drizzle-orm";
 import { auth } from "@/auth";
 import { db } from "@/lib/db/client";
 import { memories, projects, projectShares } from "@/lib/db/schema";
 import { searchMemories } from "@/lib/memories";
-import { getUserGroupNames, readableProjectIds } from "@/lib/access";
+import {
+  getAccessibleProjects,
+  getUserGroupNames,
+  type AccessibleProject,
+} from "@/lib/access";
+import { ProjectCombobox } from "./_project-combobox";
 import { Container, PageHeader } from "@/app/_components/ui/container";
 import { Card, CardBody } from "@/app/_components/ui/card";
 import { Badge } from "@/app/_components/ui/badge";
@@ -50,12 +55,12 @@ async function fetchMemoriesByIds(
 
 async function listRecent(
   userId: string,
-  groupNames: string[],
+  accessible: AccessibleProject[],
   scope?: Scope,
   project?: string,
 ): Promise<MemoryRow[]> {
   // Visibility: own rows OR rows in an accessible project.
-  const accessibleIds = await readableProjectIds(userId, groupNames);
+  const accessibleIds = accessible.map((p) => p.projectId);
   const visibility =
     accessibleIds.length > 0
       ? or(eq(memories.userId, userId), inArray(memories.projectId, accessibleIds))
@@ -63,17 +68,18 @@ async function listRecent(
   const filters = [visibility!, isNull(memories.deletedAt)];
   if (scope) filters.push(eq(memories.scope, scope));
   if (project) {
-    // Project filter — match the project key against any project the
+    // Project filter — resolve the typed key against the projects the
-    // user can read (owned or shared). When the key matches none of
+    // user can read (owned or shared), owned winning on a key collision
-    // those, return empty.
+    // to match project.identify / the search path. Filtering by the
-    filters.push(
+    // resolved id keeps the WHERE clause a plain equality — no raw-SQL
-      sql`${memories.projectId} IN (
+    // array binding (the source of the earlier memory.list crash). When
-        SELECT id FROM ${projects}
+    // the key matches no accessible project, return empty.
-        WHERE ${projects.key} = ${project}
+    const matches = accessible.filter((p) => p.projectKey === project);
-          AND (${projects.userId} = ${userId}
+    const resolvedId =
-               OR ${projects.id} = ANY(${accessibleIds}::uuid[]))
+      matches.find((p) => p.access === "owner")?.projectId ??
-      )`,
+      matches[0]?.projectId;
-    );
+    if (!resolvedId) return [];
+    filters.push(eq(memories.projectId, resolvedId));
   }
   const rows = await db
     .select({
@@ -120,6 +126,15 @@ export default async function MemoriesPage({
   const scope = params.scope === "user" || params.scope === "project" ? params.scope : undefined;
   const project = params.project?.trim() || undefined;
 
+  // Projects the user can read (owned ∪ shared). Reused both to build the
+  // list-path WHERE clause and to populate the project filter's type-ahead
+  // suggestions. Keys are deduped (a key can appear once per owned/shared
+  // project) and sorted for a stable dropdown order.
+  const accessible = await getAccessibleProjects(userId, groupNames);
+  const projectKeys = [...new Set(accessible.map((p) => p.projectKey))].sort(
+    (a, b) => a.localeCompare(b),
+  );
+
   let rows: MemoryRow[] = [];
   let debug: { vec: number; fts: number; tag: number } | null = null;
 
@@ -138,7 +153,7 @@ export default async function MemoriesPage({
     });
     debug = result.debug;
   } else {
-    rows = await listRecent(userId, groupNames, scope, project);
+    rows = await listRecent(userId, accessible, scope, project);
   }
 
   // Annotate which rows belong to projects that have any active share.
@@ -182,10 +197,10 @@ export default async function MemoriesPage({
           className="flex-1 min-w-[200px]"
         />
         <FilterSelect name="scope" value={scope} options={["", "project", "user"]} placeholder="Any scope" />
-        <Input
+        <ProjectCombobox
           name="project"
-          placeholder="Project key…"
           defaultValue={project ?? ""}
+          options={projectKeys}
           className="w-44"
         />
         <Button type="submit" variant="secondary">Apply</Button>

apps/web/app/(authed)/settings/page.tsx

@@ -63,7 +63,9 @@ export default async function SettingsPage() {
           </CardHeader>
           <CardBody className="text-sm text-fg-muted">
             OIDC group memberships from your IdP, refreshed at sign-in. Used
-            by the upcoming sharing feature to scope project visibility.
+            to scope project sharing &mdash; memories and snippets in a shared
+            project are readable by member groups and editable by read-write
+            groups.
           </CardBody>
         </Card>
       </div>

apps/web/app/(authed)/settings/tokens/page.tsx

@@ -108,6 +108,44 @@ async function revokeTokenAction(formData: FormData) {
   revalidatePath("/settings/tokens");
 }
 
+/**
+ * Points people at the plugin before they mint a token they don't need.
+ *
+ * Rendered only when this instance knows which marketplace it's published
+ * from — showing a copyable command that points nowhere is worse than showing
+ * nothing.
+ */
+function PluginHint({
+  marketplaceUrl,
+  marketplaceName,
+}: {
+  marketplaceUrl: string | undefined;
+  marketplaceName: string;
+}) {
+  if (!marketplaceUrl) return null;
+  return (
+    <Card className="mb-6">
+      <CardHeader className="text-sm font-medium text-fg">
+        If this machine has a browser, install the plugin instead
+      </CardHeader>
+      <CardBody>
+        <p className="text-sm text-fg-muted mb-3">
+          The plugin signs you in through {" "}
+          <span className="text-fg">your usual login</span>, so there&apos;s no
+          token to copy, store, or rotate. Generate a token below only when a
+          browser sign-in isn&apos;t possible.
+        </p>
+        <pre className="text-xs !whitespace-pre-wrap !break-all select-all">
+          {[
+            `claude plugin marketplace add ${marketplaceUrl}`,
+            `claude plugin install shared-memory@${marketplaceName}`,
+          ].join("\n")}
+        </pre>
+      </CardBody>
+    </Card>
+  );
+}
+
 export default async function TokensPage() {
   const session = await auth();
   const userId = session!.user.id;
@@ -144,7 +182,12 @@ export default async function TokensPage() {
     <Container className="pt-6 max-w-3xl">
       <PageHeader
         title="CLI tokens"
-        description={`Long-lived bearer tokens for MCP clients without browser access. ${ttlDays}-day expiry per token.`}
+        description={`For machines that can't complete a browser sign-in — headless containers, CI runners, sealed devboxes. Tokens last ${ttlDays} days and can be revoked one at a time.`}
+      />
+
+      <PluginHint
+        marketplaceUrl={env().PLUGIN_MARKETPLACE_URL}
+        marketplaceName={env().PLUGIN_MARKETPLACE_NAME}
       />
 
       <Card className="mb-6">

apps/web/app/.well-known/oauth-protected-resource/route.ts

@@ -1,5 +1,6 @@
 import { NextResponse } from "next/server";
 import { env } from "@/lib/env";
+import { mcpIssuer } from "@/lib/auth/jwt";
 
 export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
@@ -12,10 +13,21 @@ export const dynamic = "force-dynamic";
  */
 export function GET() {
   const resource = env().PUBLIC_URL.replace(/\/$/, "");
+
+  // The audience scope MUST be advertised. Authentik only evaluates a scope
+  // mapping when the client requests that scope by name, and the client only
+  // learns scope names from this document. Omit it and every access token
+  // arrives without `aud`, which jwt.ts rejects as "claim invalid: aud".
+  const audienceScope =
+    env().OIDC_AUDIENCE_SCOPE ?? `aud-${env().OIDC_AUDIENCE}`;
+
   return NextResponse.json({
     resource,
-    authorization_servers: [env().OIDC_ISSUER],
+    // The MCP application's issuer, which is not necessarily the Web UI's —
-    scopes_supported: ["openid", "profile", "email"],
+    // see mcpIssuer(). Advertising the wrong one sends clients to a discovery
+    // document whose tokens this endpoint will then reject on `iss`.
+    authorization_servers: [mcpIssuer()],  // as configured, slash and all
+    scopes_supported: ["openid", "profile", "email", audienceScope],
     bearer_methods_supported: ["header"],
     resource_documentation: `${resource}/`,
   });

apps/web/app/icon.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="shared-memory">
+  <title>shared-memory</title>
+  <rect width="64" height="64" rx="14" fill="#11151b"/>
+  <!--
+    Three retrieval signals - vector, full-text, tags - converging on a single
+    memory. The direct match runs straight through at full strength; the two
+    ranked neighbours fall back, which is the fusion the search actually does.
+    Opacity is held equal on the outer pair so the mark stays balanced at 16px.
+  -->
+  <g fill="none" stroke-linecap="round" stroke-width="7">
+    <path d="M13 15C25 15 26 32 35 32" stroke="#0092fd" opacity=".55"/>
+    <path d="M13 32H35" stroke="#49a9ff"/>
+    <path d="M13 49C25 49 26 32 35 32" stroke="#0092fd" opacity=".55"/>
+  </g>
+  <circle cx="45" cy="32" r="7.5" fill="#76c0ff"/>
+</svg>

apps/web/lib/auth/jwt.ts

@@ -23,13 +23,39 @@ type GlobalWithJwks = typeof globalThis & {
 };
 const g = globalThis as GlobalWithJwks;
 
+/**
+ * Issuer of MCP access tokens. The MCP endpoint is a separate application in
+ * the IdP from the Web UI, and Authentik stamps each token with its own
+ * application slug, so this is NOT interchangeable with OIDC_ISSUER.
+ */
+export function mcpIssuer(): string {
+  return env().OIDC_ISSUER_MCP ?? env().OIDC_ISSUER;
+}
+
+/**
+ * Issuer values accepted for the `iss` claim.
+ *
+ * jose compares `iss` by exact string, and IdPs are inconsistent about the
+ * trailing slash: Authentik emits `.../application/o/<slug>/` while the same
+ * value is routinely configured without it. Normalizing to one form and
+ * comparing against that fails whenever the two disagree — which is exactly
+ * how this broke: the URL-safe (stripped) form was reused for the claim check
+ * against a token whose `iss` ended in a slash.
+ *
+ * Accept both spellings rather than making correctness depend on how someone
+ * typed an env var.
+ */
+function acceptedIssuers(): [string, string] {
+  const bare = mcpIssuer().replace(/\/$/, "");
+  return [bare, `${bare}/`];
+}
+
 function jwks() {
   if (g.__sharedMemoryJwks) return g.__sharedMemoryJwks;
   // Authentik discovery is at `${issuer}/.well-known/openid-configuration`;
   // the JWKS URI is normally `${issuer}/jwks/` or `${issuer}/.well-known/jwks.json`.
   // Authentik canonically serves `${issuer}/jwks/`.
-  const issuer = env().OIDC_ISSUER.replace(/\/$/, "");
+  const url = new URL(`${mcpIssuer().replace(/\/$/, "")}/jwks/`);
-  const url = new URL(`${issuer}/jwks/`);
   g.__sharedMemoryJwks = createRemoteJWKSet(url, {
     cacheMaxAge: 10 * 60 * 1000, // 10 min
     cooldownDuration: 30 * 1000,
@@ -118,7 +144,7 @@ export async function authenticateBearer(authHeader: string | null): Promise<Aut
     }
 
     const { payload } = await jwtVerify(token, jwks(), {
-      issuer: env().OIDC_ISSUER,
+      issuer: acceptedIssuers(),
       audience: env().OIDC_AUDIENCE,
     });
     if (!payload.sub) {
@@ -127,7 +153,24 @@ export async function authenticateBearer(authHeader: string | null): Promise<Aut
         buildWwwAuthenticate("invalid_token", "missing sub"),
       );
     }
-    return { ...payload, groups: extractGroupsClaim(payload) } as AuthenticatedClaims;
+    // Normalize the issuer for identity purposes.
+    //
+    // The token was just verified against mcpIssuer() — that check is done.
+    // But identity is keyed on (oidc_iss, oidc_sub), and the Web UI signs
+    // people in through a DIFFERENT application whose tokens carry
+    // OIDC_ISSUER. Authentik's `sub` is stable across providers (it is
+    // `user.uid`, a user-level value), so the only thing that differs is the
+    // issuer.
+    //
+    // Leave it un-normalized and userContextFromClaims — which UPSERTS rather
+    // than failing — quietly creates a SECOND user row for the same human:
+    // MCP writes would land in an account with none of their memories, and
+    // nothing would look broken. Pin identity to the canonical issuer.
+    return {
+      ...payload,
+      iss: env().OIDC_ISSUER,
+      groups: extractGroupsClaim(payload),
+    } as AuthenticatedClaims;
   } catch (err) {
     if (err instanceof UnauthorizedError) throw err;
     const desc =

apps/web/lib/env.ts

@@ -4,6 +4,16 @@ const Bool = z
   .union([z.boolean(), z.enum(["true", "false", "1", "0"])])
   .transform((v) => v === true || v === "true" || v === "1");
 
+/**
+ * Treat an empty string as "not set".
+ *
+ * docker-compose renders `${VAR:-}` as an empty string rather than omitting
+ * the key, so an unset optional var arrives as "" and would otherwise fail
+ * `.url()` / `.min(1)` validation and take the whole app down at boot.
+ */
+const optional = <T extends z.ZodTypeAny>(schema: T) =>
+  z.preprocess((v) => (v === "" ? undefined : v), schema.optional());
+
 const envSchema = z.object({
   NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
   LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
@@ -13,11 +23,35 @@ const envSchema = z.object({
 
   // Authentik OIDC
   OIDC_ISSUER: z.string().url(),
+
+  // Issuer of MCP *access tokens*, when it differs from OIDC_ISSUER.
+  //
+  // The Web UI and the MCP endpoint are two separate applications in the IdP,
+  // and Authentik's default `per_provider` issuer mode stamps each token with
+  // its own application slug. So the web app issues
+  // `.../application/o/<slug>/` while the MCP provider issues
+  // `.../application/o/<slug>-mcp/`, and verifying MCP tokens against
+  // OIDC_ISSUER fails with "claim invalid: iss".
+  //
+  // Set this to the MCP application's issuer. Defaults to OIDC_ISSUER for
+  // single-application setups.
+  OIDC_ISSUER_MCP: optional(z.string().url()),
   OIDC_CLIENT_ID_WEB: z.string().min(1),
   OIDC_CLIENT_SECRET_WEB: z.string().min(1),
   OIDC_CLIENT_ID_MCP: z.string().min(1),
   OIDC_AUDIENCE: z.string().min(1),
 
+  // Name of the IdP scope whose mapping emits `aud: <OIDC_AUDIENCE>`.
+  //
+  // Most IdPs (Authentik included) only evaluate a scope mapping when the
+  // client actually requests that scope. The MCP client learns which scopes
+  // to request from `scopes_supported` in our protected-resource metadata,
+  // so this name has to be advertised there or the mapping never runs and
+  // every token arrives without an `aud` claim (-> 401 "claim invalid: aud").
+  //
+  // Defaults to the `aud-<audience>` convention used in the README setup.
+  OIDC_AUDIENCE_SCOPE: optional(z.string().min(1)),
+
   // Database
   DATABASE_URL: z.string().url(),
 
@@ -33,6 +67,13 @@ const envSchema = z.object({
   // every issued CLI token at once.
   CLI_TOKEN_SECRET: z.string().min(32, "CLI_TOKEN_SECRET must be at least 32 chars"),
 
+  // Plugin marketplace this instance is published from. When set, the CLI
+  // tokens page shows the one-command plugin install, so people only mint a
+  // bearer token when their machine genuinely can't complete a browser
+  // sign-in. Left unset, that hint is hidden rather than shown wrong.
+  PLUGIN_MARKETPLACE_URL: optional(z.string().url()),
+  PLUGIN_MARKETPLACE_NAME: z.string().min(1).default("shared-memory"),
+
   // Behavior flags
   ALLOW_INSECURE_HTTP: Bool.optional().default(false),
 });
@@ -76,6 +117,7 @@ function buildPhaseStub(): Env {
     EMBEDDING_DIM: 384,
     NEXTAUTH_SECRET: "build-phase-secret-not-used-at-runtime-xxxxxxxx",
     CLI_TOKEN_SECRET: "build-phase-secret-not-used-at-runtime-xxxxxxxx",
+    PLUGIN_MARKETPLACE_NAME: "shared-memory",
     ALLOW_INSECURE_HTTP: false,
   };
 }

apps/web/public/logo.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="shared-memory">
+  <title>shared-memory</title>
+  <!--
+    Transparent, currentColor variant of the mark for in-app use - inherits
+    the surrounding text color so it works on any surface. The tile version
+    used as the favicon lives at app/icon.svg.
+  -->
+  <g fill="none" stroke="currentColor" stroke-linecap="round" stroke-width="7">
+    <path d="M13 15C25 15 27 32 37 32" opacity=".45"/>
+    <path d="M13 32H37"/>
+    <path d="M13 49C25 49 27 32 37 32" opacity=".7"/>
+  </g>
+  <circle cx="43" cy="32" r="8" fill="currentColor"/>
+</svg>

docker-compose.yml

@@ -113,6 +113,12 @@ services:
       OIDC_CLIENT_SECRET_WEB: ${OIDC_CLIENT_SECRET_WEB:?required}
       OIDC_CLIENT_ID_MCP: ${OIDC_CLIENT_ID_MCP:?required}
       OIDC_AUDIENCE: ${OIDC_AUDIENCE:?required}
+      # Optional. This block is an explicit allow-list, not env_file — a var
+      # added to .env but not listed here never reaches the container.
+      OIDC_ISSUER_MCP: ${OIDC_ISSUER_MCP:-}
+      OIDC_AUDIENCE_SCOPE: ${OIDC_AUDIENCE_SCOPE:-}
+      PLUGIN_MARKETPLACE_URL: ${PLUGIN_MARKETPLACE_URL:-}
+      PLUGIN_MARKETPLACE_NAME: ${PLUGIN_MARKETPLACE_NAME:-shared-memory}
 
       DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
 

plugin/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
+  "name": "shared-memory",
+  "version": "0.1.0",
+  "description": "Shared persistent memory and snippet library for Claude Code sessions, backed by your own shared-memory server and authenticated with OIDC.",
+  "author": {
+    "name": "CyberCove Labs"
+  },
+  "homepage": "https://repo.anhonesthost.net/cybercove-labs/shared-memory"
+}

plugin/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "shared-memory": {
+      "type": "http",
+      "url": "https://memory.example.com/api/mcp",
+      "oauth": {
+        "clientId": "<OIDC_CLIENT_ID_MCP>",
+        "callbackPort": 33418
+      }
+    }
+  }
+}