docs: describe project sharing as shipped on the settings page

The Groups card still called sharing "the upcoming sharing feature". It has
shipped — memory_visibility, groups, user_groups and project_shares are all
live — so the card now describes what group membership actually does:
read access for member groups, write access for read-write groups.

Authored on the fix/memory-list-project-filter branch on 2026-07-05 and never
committed; that branch is otherwise fully merged via PR #7.

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

.env.example

@@ -40,6 +40,12 @@ 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

README.md

@@ -145,6 +145,8 @@ Copy `.env.example` and fill in the values below.
 | `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`. |
@@ -335,6 +337,13 @@ reliable pattern:
 > 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`.

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/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

@@ -135,7 +135,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"),
@@ -25,7 +35,7 @@ const envSchema = z.object({
   //
   // Set this to the MCP application's issuer. Defaults to OIDC_ISSUER for
   // single-application setups.
-  OIDC_ISSUER_MCP: z.string().url().optional(),
+  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),
@@ -40,7 +50,7 @@ const envSchema = z.object({
   // 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: z.string().min(1).optional(),
+  OIDC_AUDIENCE_SCOPE: optional(z.string().min(1)),
 
   // Database
   DATABASE_URL: z.string().url(),
@@ -57,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),
 });
@@ -100,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}