@ferrule-io/ok-fine 0.3.11 → 0.3.13

package/dist/auth/verifier.js

@@ -97,14 +97,7 @@ export class JwtTokenVerifier {
                 }
             }
             if (requiredGroups.length > 0) {
-                const groupsVal = payload[groupsClaim];
-                let tokenGroups = [];
-                if (typeof groupsVal === "string") {
-                    tokenGroups = [groupsVal];
-                }
-                else if (Array.isArray(groupsVal)) {
-                    tokenGroups = groupsVal.filter((g) => typeof g === "string");
-                }
+                const tokenGroups = readGroups(payload[groupsClaim]);
                 const hasRequiredGroup = tokenGroups.some((g) => requiredGroups.includes(g));
                 if (!hasRequiredGroup) {
                     throw new OAuthError(OAuthErrorCode.InsufficientScope, "token not permitted by this server's access policy");
@@ -133,6 +126,7 @@ export class JwtTokenVerifier {
                 break;
             }
         }
+        const groups = readGroups(payload[this.access?.groupsClaim ?? "groups"]);
         return {
             token,
             clientId,
@@ -141,10 +135,19 @@ export class JwtTokenVerifier {
             extra: {
                 sub: typeof payload.sub === "string" ? payload.sub : "unknown",
                 identity,
+                groups,
             },
         };
     }
 }
+/** Normalizes a groups claim, accepted as a string or an array of strings. */
+function readGroups(value) {
+    if (typeof value === "string")
+        return [value];
+    if (Array.isArray(value))
+        return value.filter((g) => typeof g === "string");
+    return [];
+}
 /**
  * Computes a Principal from an AuthInfo and configured scope names.
  * Hierarchy:
@@ -161,12 +164,15 @@ export function principalFromAuthInfo(info, scopeNames) {
     const canRead = hasRead || hasWrite || hasAdmin;
     const extraSub = info.extra?.sub;
     const extraIdentity = info.extra?.identity;
+    const extraGroups = info.extra?.groups;
     const sub = typeof extraSub === "string" ? extraSub : "unknown";
     const identity = typeof extraIdentity === "string" ? extraIdentity : null;
+    const groups = Array.isArray(extraGroups) ? extraGroups.filter((g) => typeof g === "string") : [];
     return {
         subject: sub,
         clientId: info.clientId,
         identity,
+        groups,
         scopes: info.scopes,
         canRead,
         canWrite,

package/dist/config.js

@@ -1,5 +1,7 @@
+import { readFileSync } from "node:fs";
 import { isIPv4 } from "node:net";
 import { z } from "zod";
+import { PROJECT_RE } from "./okf/paths.js";
 /** A whole-string decimal integer env var (rejects `8080junk`, `1x`, `1.5`, and blanks). */
 function intEnv(name, fallback, min, max = Number.MAX_SAFE_INTEGER) {
     return z
@@ -73,6 +75,10 @@ const storageEnvShape = {
         .default("/data")
         .refine((v) => v.startsWith("/"), "DATA_DIR must be an absolute path"),
     GIT_BRANCH: z.string().default("main"),
+    HUB_PROJECT: z
+        .string()
+        .default("org")
+        .transform((v) => (v.trim() === "" ? "org" : v.trim())),
     GIT_REMOTE_URL: z.string().optional(),
     GIT_SYNC_INTERVAL_SECONDS: intEnv("GIT_SYNC_INTERVAL_SECONDS", "60", 0),
     GIT_SSH_KEY_PATH: z.string().optional(),
@@ -82,7 +88,98 @@ const storageEnvShape = {
     MAX_FILE_BYTES: intEnv("MAX_FILE_BYTES", "1048576", 1),
     MAX_ARCHIVE_BYTES: intEnv("MAX_ARCHIVE_BYTES", "52428800", 1),
     DEFAULT_STALE_AFTER_DAYS: optionalIntEnv("DEFAULT_STALE_AFTER_DAYS", 1, 36500),
+    PROJECT_ACCESS: z.string().optional(),
+    PROJECT_ACCESS_FILE: z.string().optional(),
 };
+const projectAccessRuleSchema = z.object({
+    readGroups: z.array(z.string()).default([]),
+    writeGroups: z.array(z.string()).default([]),
+});
+const projectAccessMapSchema = z.record(z.string(), projectAccessRuleSchema);
+function refineProjectAccess(data, ctx) {
+    if (data.PROJECT_ACCESS && data.PROJECT_ACCESS_FILE) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["PROJECT_ACCESS"],
+            message: "PROJECT_ACCESS and PROJECT_ACCESS_FILE cannot both be set",
+        });
+        return;
+    }
+    let jsonStr;
+    let targetPath = "PROJECT_ACCESS";
+    if (data.PROJECT_ACCESS !== undefined && data.PROJECT_ACCESS.trim() !== "") {
+        jsonStr = data.PROJECT_ACCESS;
+        targetPath = "PROJECT_ACCESS";
+    }
+    else if (data.PROJECT_ACCESS_FILE !== undefined && data.PROJECT_ACCESS_FILE.trim() !== "") {
+        targetPath = "PROJECT_ACCESS_FILE";
+        try {
+            jsonStr = readFileSync(data.PROJECT_ACCESS_FILE, "utf-8");
+        }
+        catch (err) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["PROJECT_ACCESS_FILE"],
+                message: `could not read PROJECT_ACCESS_FILE: ${err.message}`,
+            });
+            return;
+        }
+    }
+    if (jsonStr === undefined)
+        return;
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonStr);
+    }
+    catch {
+        ctx.addIssue({
+            code: "custom",
+            path: [targetPath],
+            message: `${targetPath} must be valid JSON`,
+        });
+        return;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        ctx.addIssue({
+            code: "custom",
+            path: [targetPath],
+            message: `${targetPath} must be a JSON object`,
+        });
+        return;
+    }
+    for (const key of Object.keys(parsed)) {
+        if (!PROJECT_RE.test(key)) {
+            ctx.addIssue({
+                code: "custom",
+                path: [targetPath, key],
+                message: `invalid project name "${key}": must match ${PROJECT_RE}`,
+            });
+        }
+    }
+    const result = projectAccessMapSchema.safeParse(parsed);
+    if (!result.success) {
+        for (const issue of result.error.issues) {
+            ctx.addIssue({
+                code: "custom",
+                path: [targetPath, ...issue.path],
+                message: issue.message,
+            });
+        }
+    }
+}
+function parseProjectAccess(projectAccess, projectAccessFile) {
+    let jsonStr;
+    if (projectAccess !== undefined && projectAccess.trim() !== "") {
+        jsonStr = projectAccess;
+    }
+    else if (projectAccessFile !== undefined && projectAccessFile.trim() !== "") {
+        jsonStr = readFileSync(projectAccessFile, "utf-8");
+    }
+    if (!jsonStr)
+        return {};
+    const parsed = JSON.parse(jsonStr);
+    return projectAccessMapSchema.parse(parsed);
+}
 const httpEnvShape = {
     AUTH_MODE: z.enum(["oidc", "none"], "AUTH_MODE must be oidc or none").default("oidc"),
     PORT: intEnv("PORT", "8080", 0, 65535),
@@ -150,6 +247,7 @@ const rawEnvSchema = z.object({ ...httpEnvShape, ...storageEnvShape }).superRefi
     if (!data || typeof data !== "object")
         return;
     refineGitCredentials(data, ctx);
+    refineProjectAccess(data, ctx);
     if (data.AUTH_MODE === "none") {
         const isLoopback = isLoopbackHost(data.HOST ?? "0.0.0.0");
         const allowUnauthenticated = data.ALLOW_UNAUTHENTICATED_NETWORK === "true";
@@ -220,7 +318,10 @@ const rawEnvSchema = z.object({ ...httpEnvShape, ...storageEnvShape }).superRefi
         }
     }
 }, { when: () => true });
-const storageEnvSchema = z.object(storageEnvShape).superRefine(refineGitCredentials, { when: () => true });
+const storageEnvSchema = z
+    .object(storageEnvShape)
+    .superRefine(refineGitCredentials, { when: () => true })
+    .superRefine(refineProjectAccess, { when: () => true });
 function formatConfigError(error) {
     const errorMessages = error.issues.map((issue) => `${issue.path.join(".") || "config"}: ${issue.message}`);
     return new Error(`Configuration errors:\n  ${errorMessages.join("\n  ")}`);
@@ -230,6 +331,7 @@ function storageFromRaw(raw, env, options) {
         logLevel: raw.LOG_LEVEL,
         dataDir: raw.DATA_DIR,
         gitBranch: raw.GIT_BRANCH,
+        hubProject: raw.HUB_PROJECT,
         gitRemoteUrl: raw.GIT_REMOTE_URL,
         gitSyncIntervalSeconds: raw.GIT_SYNC_INTERVAL_SECONDS,
         gitSshKeyPath: raw.GIT_SSH_KEY_PATH,
@@ -244,6 +346,7 @@ function storageFromRaw(raw, env, options) {
         maxFileBytes: raw.MAX_FILE_BYTES,
         maxArchiveBytes: raw.MAX_ARCHIVE_BYTES,
         defaultStaleAfterDays: raw.DEFAULT_STALE_AFTER_DAYS,
+        projectAccess: parseProjectAccess(raw.PROJECT_ACCESS, raw.PROJECT_ACCESS_FILE),
     };
 }
 /** Storage-only settings for the stdio transport: needs neither PUBLIC_BASE_URL nor OAUTH_*. */

package/dist/http/rest.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { OkfError } from "../errors.js";
 import { parseFrontmatter, splitFrontmatter } from "../okf/frontmatter.js";
+import { TRUST_TIERS } from "../okf/semantics.js";
 const projectParams = z.object({ project: z.string() });
 const wildcardParams = z.object({ project: z.string(), "*": z.string() });
 function principalOf(req) {
@@ -95,7 +96,7 @@ const searchQuery = z.object({
     type: z.string().optional(),
     tag: z.union([z.string(), z.array(z.string())]).optional(),
     status: z.enum(["draft", "stable", "deprecated"]).optional(),
-    trustTier: z.enum(["unverified", "machine-confirmed", "human-reviewed"]).optional(),
+    trustTier: z.enum(TRUST_TIERS).optional(),
     stale: z.enum(["true", "false"]).optional(),
     limit: z.coerce.number().int().min(1).max(100).optional(),
 });
@@ -104,8 +105,24 @@ export function registerRestRoutes(app, service) {
     const write = { permission: "write" };
     const admin = { permission: "admin" };
     app.get("/api/v1/projects", { config: read }, async (req) => {
-        const { repository } = z.object({ repository: z.string().optional() }).parse(req.query);
-        return service.listProjects({ repository });
+        const { repository, team, query } = z
+            .object({
+            repository: z.string().optional(),
+            team: z.string().optional(),
+            query: z.string().optional(),
+        })
+            .parse(req.query);
+        return service.listProjects(principalOf(req), { repository, team, query });
+    });
+    app.get("/api/v1/orient", { config: read }, async (req) => {
+        const { question, project, limit } = z
+            .object({
+            question: z.string().min(1).max(512),
+            project: z.string().optional(),
+            limit: z.coerce.number().int().min(1).max(50).optional(),
+        })
+            .parse(req.query);
+        return service.orient(principalOf(req), { question, project, limit });
     });
     app.post("/api/v1/projects", { config: write }, async (req, reply) => {
         const body = z
@@ -116,7 +133,7 @@ export function registerRestRoutes(app, service) {
     });
     app.get("/api/v1/projects/:project", { config: read }, async (req) => {
         const { project } = projectParams.parse(req.params);
-        return service.getProject(project);
+        return service.getProject(principalOf(req), project);
     });
     app.delete("/api/v1/projects/:project", { config: admin }, async (req) => {
         const { project } = projectParams.parse(req.params);
@@ -125,11 +142,11 @@ export function registerRestRoutes(app, service) {
     app.get("/api/v1/projects/:project/index", { config: read }, async (req) => {
         const { project } = projectParams.parse(req.params);
         const { path } = z.object({ path: z.string().optional() }).parse(req.query);
-        return service.getIndex(project, path ?? "");
+        return service.getIndex(principalOf(req), project, path ?? "");
     });
     app.get("/api/v1/projects/:project/concepts/*", { config: read }, async (req, reply) => {
         const { project, "*": id } = wildcardParams.parse(req.params);
-        const concept = withRevision(reply, await service.readConcept(project, id));
+        const concept = withRevision(reply, await service.readConcept(principalOf(req), project, id));
         if ((req.headers.accept ?? "").includes("text/markdown")) {
             return reply.type("text/markdown; charset=utf-8").send(concept.markdown);
         }
@@ -172,7 +189,7 @@ export function registerRestRoutes(app, service) {
     });
     app.get("/api/v1/projects/:project/files/*", { config: read }, async (req, reply) => {
         const { project, "*": path } = wildcardParams.parse(req.params);
-        const file = withRevision(reply, await service.readFile(project, path));
+        const file = withRevision(reply, await service.readFile(principalOf(req), project, path));
         const extension = /\.[^./]+$/.exec(path)?.[0].toLowerCase() ?? "";
         return reply.type(CONTENT_TYPE_BY_EXTENSION[extension] ?? "text/plain; charset=utf-8").send(file.content);
     });
@@ -203,19 +220,19 @@ export function registerRestRoutes(app, service) {
         const { id, limit } = z
             .object({ id: z.string().optional(), limit: z.coerce.number().int().min(1).max(100).optional() })
             .parse(req.query);
-        return service.history(project, id, limit);
+        return service.history(principalOf(req), project, id, limit);
     });
     app.get("/api/v1/projects/:project/lint", { config: read }, async (req) => {
         const { project } = projectParams.parse(req.params);
-        return service.lint(project);
+        return service.lint(principalOf(req), project);
     });
     app.get("/api/v1/projects/:project/conflicts", { config: read }, async (req) => {
         const { project } = projectParams.parse(req.params);
-        return service.listConflicts(project);
+        return service.listConflicts(principalOf(req), project);
     });
     app.get("/api/v1/projects/:project/conflicts/:id/files/*", { config: read }, async (req) => {
         const { project, id, "*": path, } = z.object({ project: z.string(), id: z.string(), "*": z.string() }).parse(req.params);
-        return service.readConflict(project, id, path);
+        return service.readConflict(principalOf(req), project, id, path);
     });
     app.post("/api/v1/projects/:project/conflicts/:id/resolution", { config: write }, async (req, reply) => {
         const { project, id } = z.object({ project: z.string(), id: z.string() }).parse(req.params);
@@ -225,7 +242,7 @@ export function registerRestRoutes(app, service) {
     });
     app.get("/api/v1/projects/:project/archive", { config: read }, async (req, reply) => {
         const { project } = projectParams.parse(req.params);
-        const stream = await service.exportArchive(project);
+        const stream = service.exportArchive(principalOf(req), project);
         return reply
             .type("application/gzip")
             .header("content-disposition", `attachment; filename="${project}.tar.gz"`)
@@ -240,7 +257,7 @@ export function registerRestRoutes(app, service) {
     });
     app.get("/api/v1/search", { config: read }, async (req) => {
         const q = searchQuery.parse(req.query);
-        return service.search({
+        return service.search(principalOf(req), {
             ...(q.q === undefined ? {} : { query: q.q }),
             ...(q.project === undefined ? {} : { project: q.project }),
             ...(q.type === undefined ? {} : { type: q.type }),

package/dist/local-host.js

@@ -85,6 +85,7 @@ export async function createLocalHost(options) {
                 subject: "local",
                 clientId: "stdio",
                 identity,
+                groups: [],
                 scopes: [],
                 canRead: true,
                 canWrite: true,

package/dist/mcp/server.js

@@ -1,13 +1,14 @@
 import { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import { OkfError } from "../errors.js";
+import { TRUST_TIERS } from "../okf/semantics.js";
 import { FEEDBACK_TYPES, feedbackLink } from "../service/feedback.js";
 import { VERSION } from "../version.js";
-export const INSTRUCTIONS = `ok-fine holds shared project knowledge outside the codebase, as OKF v0.2 markdown concepts grouped into projects. In a git repository, first run \`git remote get-url origin\` and call list_projects with that URL as \`repository\`; use the returned project(s) for every read and write. If none match, say the repository is not onboarded and offer to onboard it (ok-fine-onboard skill). Search before planning or editing; record durable decisions, conventions, and runbooks afterwards.
-1. Discover: get_index (progressive disclosure) or search_concepts with \`project\`.
-2. Read: read_concept returns frontmatter, body, trust tier (unverified | machine-confirmed | human-reviewed), staleness, and links. Freshness comes first: a concept that is stale, when its code sources changed since \`sources[].commit\`, or when that commit is not an ancestor of HEAD (unmerged or rebased away), is a lead to re-check whatever its tier; among fresh concepts prefer higher trust tiers. Knowledge about unmerged work goes into \`proposals/<slug>\` concepts with a \`proposal: { ref: <URI> }\` frontmatter key, never into current-state concepts; concepts carrying \`proposal\` are not current truth. Deprecated concepts are history; when code contradicts a concept, trust the code and update the concept.
-3. Write: write_concept with frontmatter containing \`type\` (e.g. Decision, Convention, Architecture, Component, Playbook, Interface, Reference) plus \`title\`, \`description\`, \`tags\`, and \`stale_after\` (ISO 8601, e.g. 180 days ahead). Record provenance in \`sources\` (each with \`resource\` and a stable \`id\`; code sources carry \`commit\`) and cite claims with footnotes [^id]. Link concepts with bundle-absolute links such as [orders](/tables/orders.md). After re-checking a concept against the code, refresh \`sources[].commit\` and \`stale_after\` with write_concept, then call verify_concept.
-4. Pass \`actor\` as <harness>/<model> (e.g. claude-code/claude-opus-4-5, codex/gpt-5-codex, gemini-cli/gemini-2.5-pro). Use human:<email>, with the email from \`git config user.email\`, only when the user personally reviewed the concept; on forbidden_actor, report both identities instead of retrying as another. The server stamps \`generated\`; \`verified\` changes only through verify_concept.
+export const INSTRUCTIONS = `ok-fine holds shared project knowledge outside the codebase, as OKF v0.2 markdown concepts grouped into projects. Project resolution order: 1) A project named explicitly by the user or by harness project/workspace instructions (e.g. Claude Project instructions, a custom GPT's instructions): use it. 2) In a git repository with a remote: call list_projects with \`repository\` set to the remote URL (\`git remote get-url origin\`, falling back to the first remote); use the returned project(s) for every read and write. If none match, say the repository is not onboarded and offer to onboard it (ok-fine-onboard skill). 3) Otherwise (no repository, no shell, or no remote): call orient with your question to rank relevant projects and concepts across the organization, or call list_projects with \`team\` and/or \`query\` (or no arguments). Never run git commands and never say "not onboarded" or offer onboarding on this path. If several fit, read from all; ask before writing only when the write target is ambiguous. Search before planning or editing; record durable decisions, conventions, and runbooks afterwards.
+1. Discover: orient (cross-org ranked discovery with working rules), get_index (progressive disclosure) or search_concepts with \`project\` (omitting \`project\` searches all projects).
+2. Read: read_concept returns frontmatter, body, trust tier (proposed | unverified | machine-confirmed | human-reviewed), staleness, and links. Freshness comes first: a concept that is stale is a lead to re-check whatever its tier. For concepts with code sources, that means when code changed since \`sources[].commit\` or that commit is not an ancestor of HEAD (unmerged or rebased away); for concepts without code sources, fresh means \`stale_after\` is set and not past (additionally, when a tool available in the session can fetch a source's \`resource\` URL and report its last-modified time, a source modified after \`generated.at\` counts as drifted). Among fresh concepts prefer higher trust tiers. Knowledge about unmerged work is written at its usual id (e.g. \`decisions/<slug>\`, never over an existing concept) with a \`proposal: { ref: <URI> }\` frontmatter key; such concepts have trust tier \`proposed\` and are not current truth. When one you read has landed in the mainline, rewrite it as current truth without the \`proposal\` key and verify it; when its work was abandoned, set \`status: deprecated\`. Deprecated concepts are history; when code contradicts a concept, trust the code and update the concept.
+3. Write: write_concept with frontmatter containing \`type\` (e.g. Decision, Convention, Architecture, Component, Playbook, Interface, Reference) plus \`title\`, \`description\`, \`tags\`, and \`stale_after\` (ISO 8601, e.g. 180 days ahead). Record provenance in \`sources\` (each with \`resource\` and a stable \`id\`; code sources carry \`commit\`; non-code sources use a URL or stable URI \`resource\` without \`commit\`) and cite claims with footnotes [^id]. Link concepts with bundle-absolute links such as [orders](/tables/orders.md). After re-checking a concept against the code or sources, refresh \`sources[].commit\` and \`stale_after\` with write_concept, then call verify_concept.
+4. Pass \`actor\` as <harness>/<model> (e.g. claude-code/claude-opus-4-5, claude-desktop/<model>, claude-ai/<model>, chatgpt/<model>, gemini-cli/gemini-2.5-pro). Use human:<email>, with the email from \`git config user.email\` in a repository or the email confirmed by the user outside one, only when the user personally reviewed the concept; on forbidden_actor, report both identities instead of retrying as another. The server stamps \`generated\`; \`verified\` changes only through verify_concept.
 5. When updating, pass expectedRevision from read_concept (null to create only).
 6. An \`unresolved_conflict\` issue (lint_project, read_concept) is a write ok-fine accepted but could not merge with a concurrent edit from another ok-fine instance. Before editing the affected file: read_conflict, merge \`preserved\` into \`current\` (use \`base\` to see what each side changed), write the result with expectedRevision set to \`current.revision\`, then call resolve_conflict with every file path of the conflict. Resolve only conflicts of the project you are working in.
 7. Prefer \`status: deprecated\` over delete_concept. index.md and log.md are maintained by the server; do not write them. A project is bound to repositories through the \`repositories\` list in its overview frontmatter.
@@ -61,67 +62,86 @@ export function createMcpServer(service, principal, log) {
     const readOnly = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
     tool("list_projects", "read", {
         title: "List projects",
-        description: "List projects (OKF bundles) with concept and staleness counts and the git repositories bound to each; pass repository to find the projects that hold a codebase's knowledge.",
+        description: "Call first to pick the project. In a git repository pass `repository` (the remote URL); outside a git repository (e.g. desktop chat), call with `team` and/or `query` (or no arguments) and choose by title, description, teams, domains, keywords; a project named by the user or project instructions wins. Lists projects (OKF bundles) with concept and staleness counts, bound git repositories, and routing metadata (teams, domains, audience, keywords, owners).",
         inputSchema: z.object({
             repository: z
                 .string()
                 .optional()
-                .describe("Git remote URL of the current repository, e.g. the output of `git remote get-url origin`; returns only the projects bound to it"),
+                .describe("Git remote URL of the current repository, e.g. the output of `git remote get-url origin`; returns only the projects bound to it. Omit outside a git repository."),
+            team: z.string().optional().describe("Case-insensitive match on the overview's `teams`"),
+            query: z
+                .string()
+                .optional()
+                .describe("Keywords matched against title, description, `domains`, and `keywords`; any term matches by word prefix"),
+        }),
+        annotations: readOnly,
+    }, (a) => service.listProjects(principal, { repository: a.repository, team: a.team, query: a.query }));
+    tool("orient", "read", {
+        title: "Orient across organization knowledge",
+        description: "Call before answering any question about how the organization works: processes, policies, customers, products, campaigns. Returns ranked projects, each with its top concepts and scores, plus working rules (freshness first, trust tier, citing sources, and rephrasing queries).",
+        inputSchema: z.object({
+            question: z
+                .string()
+                .min(1)
+                .max(512)
+                .describe("The user's question, task, or search terms to orient against (max 512 chars)"),
+            project: z.string().optional().describe("Restrict orientation to a single project"),
+            limit: z.number().int().min(1).max(50).optional().describe("Maximum projects to return (default: 5)"),
         }),
         annotations: readOnly,
-    }, (a) => service.listProjects({ repository: a.repository }));
+    }, (a) => service.orient(principal, { question: a.question, project: a.project, limit: a.limit }));
     tool("get_index", "read", {
         title: "Get directory index",
         description: "Progressive-disclosure listing of one bundle directory: its concepts grouped by type, files, and subdirectories.",
         inputSchema: z.object({ project, path: z.string().optional().describe("directory, default bundle root") }),
         annotations: readOnly,
-    }, (a) => service.getIndex(a.project, a.path ?? ""));
+    }, (a) => service.getIndex(principal, a.project, a.path ?? ""));
     tool("read_concept", "read", {
         title: "Read concept",
         description: "Read one concept with frontmatter, body, derived trust/staleness, links, and lint issues; returns `revision` to pass back as expectedRevision when updating.",
         inputSchema: z.object({ project, id }),
         annotations: readOnly,
-    }, (a) => service.readConcept(a.project, a.id));
+    }, (a) => service.readConcept(principal, a.project, a.id));
     tool("search_concepts", "read", {
         title: "Search concepts",
-        description: "Keyword full-text search over concepts, optionally filtered by project, type, tags, status, trust tier, and staleness.",
+        description: "Keyword full-text search over concepts, optionally filtered by project, type, tags, status, trust tier, and staleness. Omitting project searches every project (use when no project is resolved yet or outside a repository); results carry project to use for follow-up read_concept calls. Cite concepts read.",
         inputSchema: z.object({
             query: z.string().max(512).optional(),
             project: z.string().optional(),
             type: z.string().optional(),
             tags: z.array(z.string()).optional(),
             status: z.enum(["draft", "stable", "deprecated"]).optional().describe("omitted hides deprecated"),
-            trustTier: z.enum(["unverified", "machine-confirmed", "human-reviewed"]).optional(),
+            trustTier: z.enum(TRUST_TIERS).optional(),
             stale: z.boolean().optional(),
             limit,
         }),
         annotations: readOnly,
-    }, (a) => service.search(a));
+    }, (a) => service.search(principal, a));
     tool("get_history", "read", {
         title: "Get history",
         description: "List git commits that changed a concept, or the whole project when id is omitted.",
         inputSchema: z.object({ project, id: id.optional(), limit }),
         annotations: readOnly,
-    }, (a) => service.history(a.project, a.id, a.limit));
+    }, (a) => service.history(principal, a.project, a.id, a.limit));
     tool("read_file", "read", {
         title: "Read file",
         description: "Read any text file in a bundle verbatim (including index.md, log.md, and non-markdown assets).",
         inputSchema: z.object({ project, path: z.string().describe("bundle-relative file path") }),
         annotations: readOnly,
-    }, (a) => service.readFile(a.project, a.path));
+    }, (a) => service.readFile(principal, a.project, a.path));
     tool("lint_project", "read", {
         title: "Lint project",
         description: "Check a bundle for OKF v0.2 conformance and return errors, warnings, and info issues.",
         inputSchema: z.object({ project }),
         annotations: readOnly,
-    }, (a) => service.lint(a.project));
+    }, (a) => service.lint(principal, a.project));
     const conflictId = z.string().describe("Conflict id from list_conflicts or an unresolved_conflict lint issue");
     tool("list_conflicts", "read", {
         title: "List conflicts",
         description: "List the project's unresolved conflicts: writes the server accepted but could not reconcile with a concurrent edit from another ok-fine instance. Each lists changed files (divergent = the current version also changed) and the commits that made them.",
         inputSchema: z.object({ project }),
         annotations: readOnly,
-    }, (a) => service.listConflicts(a.project));
+    }, (a) => service.listConflicts(principal, a.project));
     tool("read_conflict", "read", {
         title: "Read conflict file",
         description: "Read one file of a conflict: `preserved` (the unapplied write), `base` (common ancestor), and `current` (with the revision to pass as expectedRevision when writing the merge). null = absent on that side.",
@@ -131,7 +151,7 @@ export function createMcpServer(service, principal, log) {
             path: z.string().describe("bundle-relative file path, e.g. tables/orders.md"),
         }),
         annotations: readOnly,
-    }, (a) => service.readConflict(a.project, a.id, a.path));
+    }, (a) => service.readConflict(principal, a.project, a.id, a.path));
     tool("resolve_conflict", "write", {
         title: "Resolve conflict",
         description: "Discard a conflict's preserved copy after merging what should survive with write_concept/write_file. `paths` must list every file of the conflict, confirming each was reconciled; only this project's part of the conflict is resolved.",

package/dist/okf/concept.js

@@ -1,5 +1,5 @@
 import { parseFrontmatter, splitFrontmatter } from "./frontmatter.js";
-import { extractLinks } from "./markdown.js";
+import { extractCrossProjectLinks, extractLinks } from "./markdown.js";
 import { blobRevision } from "./paths.js";
 import { displayTitle, effectiveStatus, generatedAt, generatedBy, lastVerifiedAt, staleAfter, trustTier, } from "./semantics.js";
 export function parseConcept(project, id, file, buf) {
@@ -26,6 +26,7 @@ export function parseConcept(project, id, file, buf) {
             generatedBy: null,
             lastVerifiedAt: null,
             outbound: [],
+            crossProjectOutbound: [],
         };
     }
     const parsed = parseFrontmatter(split.yaml);
@@ -49,6 +50,7 @@ export function parseConcept(project, id, file, buf) {
             generatedBy: null,
             lastVerifiedAt: null,
             outbound: [],
+            crossProjectOutbound: [],
         };
     }
     const { data } = parsed;
@@ -72,6 +74,7 @@ export function parseConcept(project, id, file, buf) {
             generatedBy: generatedBy(data),
             lastVerifiedAt: lastVerifiedAt(data),
             outbound: extractLinks(split.body, id),
+            crossProjectOutbound: extractCrossProjectLinks(split.body),
         };
     }
     const tags = Array.isArray(data.tags) ? data.tags.filter((t) => typeof t === "string") : [];
@@ -94,6 +97,7 @@ export function parseConcept(project, id, file, buf) {
         generatedBy: generatedBy(data),
         lastVerifiedAt: lastVerifiedAt(data),
         outbound: extractLinks(split.body, id),
+        crossProjectOutbound: extractCrossProjectLinks(split.body),
     };
 }
 //# sourceMappingURL=concept.js.map

package/dist/okf/lint.js

@@ -1,6 +1,6 @@
 import { posix } from "node:path";
 import { parseFrontmatter, splitFrontmatter } from "./frontmatter.js";
-import { computationBlocks, extractFootnoteLabels, extractLinks, hasLegacyCitations } from "./markdown.js";
+import { computationBlocks, extractCrossProjectLinks, extractFootnoteLabels, extractLinks, hasLegacyCitations, } from "./markdown.js";
 import { ISO_DATETIME, isStale, parseActor } from "./semantics.js";
 const COMMIT_RE = /^[0-9a-f]{7,64}$/i;
 const SHELL_META_OR_WHITESPACE = /[\s`$;|&<>()\\"'`]/;
@@ -371,6 +371,20 @@ export function lintConceptFile(path, text, ctx) {
             });
         }
     }
+    // Warning: cross-project outbound links
+    if (ctx.crossProjectConceptExists) {
+        const crossLinks = extractCrossProjectLinks(body);
+        for (const target of crossLinks) {
+            if (!ctx.crossProjectConceptExists(target.project, target.id)) {
+                issues.push({
+                    severity: "warning",
+                    code: "broken_cross_link",
+                    path,
+                    message: `cross-project link to "okf://${target.project}/${target.id}" does not exist`,
+                });
+            }
+        }
+    }
     // Info: stale
     if (isStale(data, ctx.now)) {
         issues.push({

package/dist/okf/log-file.js

@@ -26,6 +26,9 @@ export function logVerificationEntry(title, id, actor, message) {
 export function logDeletionEntry(id, actor, message) {
     return appendMessage(`**Deletion**: Removed \`${id}\` (by ${actor}).`, message);
 }
+export function logMoveEntry(title, fromId, toId, actor) {
+    return `**Move**: Moved \`${fromId}\` to [${title}](/${toId}.md) (by ${actor}).`;
+}
 export function logFileUpdateEntry(path, actor, message) {
     return appendMessage(`**Update**: Wrote file \`${path}\` (by ${actor}).`, message);
 }

package/dist/okf/markdown.js

@@ -1,8 +1,90 @@
 import { posix } from "node:path";
 import { marked } from "marked";
-import { isReservedName } from "./paths.js";
+import { isReservedName, PROJECT_RE, SEGMENT_RE } from "./paths.js";
 const SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i;
 const FOOTNOTE_RE = /\[\^([^\]\s]+)\](?!:)/g;
+export function parseCrossProjectTarget(rawHref) {
+    if (!rawHref) {
+        return null;
+    }
+    let href = rawHref;
+    try {
+        href = decodeURI(href);
+    }
+    catch {
+        // ignore URI decode failures
+    }
+    if (href.includes("\\")) {
+        return null;
+    }
+    const trimmed = href.trim();
+    if (!trimmed.toLowerCase().startsWith("okf://")) {
+        return null;
+    }
+    let withoutHash = trimmed;
+    const hashIdx = withoutHash.indexOf("#");
+    if (hashIdx !== -1) {
+        withoutHash = withoutHash.slice(0, hashIdx);
+    }
+    const queryIdx = withoutHash.indexOf("?");
+    if (queryIdx !== -1) {
+        withoutHash = withoutHash.slice(0, queryIdx);
+    }
+    const rest = withoutHash.slice(6);
+    const slashIdx = rest.indexOf("/");
+    if (slashIdx === -1) {
+        return null;
+    }
+    const project = rest.slice(0, slashIdx);
+    if (!PROJECT_RE.test(project)) {
+        return null;
+    }
+    let target = rest.slice(slashIdx + 1);
+    if (target.endsWith(".md")) {
+        target = target.slice(0, -3);
+    }
+    if (target.length === 0 || target.length > 512) {
+        return null;
+    }
+    const segments = target.split("/");
+    if (segments.length > 12) {
+        return null;
+    }
+    for (const seg of segments) {
+        if (!SEGMENT_RE.test(seg)) {
+            return null;
+        }
+    }
+    const lastSeg = segments[segments.length - 1];
+    if (!lastSeg) {
+        return null;
+    }
+    const lastLower = lastSeg.toLowerCase();
+    if (lastLower === "index" || lastLower === "log") {
+        return null;
+    }
+    return { project, id: segments.join("/") };
+}
+export function extractCrossProjectLinks(body) {
+    const tokens = marked.lexer(body);
+    const found = [];
+    const seen = new Set();
+    marked.walkTokens(tokens, (token) => {
+        if (token.type !== "link" || token.raw.startsWith("[^")) {
+            return;
+        }
+        const target = parseCrossProjectTarget(token.href);
+        if (!target) {
+            return;
+        }
+        const key = `${target.project}/${target.id}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            found.push(target);
+        }
+    });
+    return found;
+}
 export function extractLinks(body, conceptId) {
     const tokens = marked.lexer(body);
     const found = [];