Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
fix(workforce): say user, not person, in FIX-1905 docs and comments
The retired-terms guard counts 'person' and 'member' where they mean the
signed-in user.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AbWGaPRHHDktemkzFXph5b
  • Loading branch information
claude committed Oct 13, 2026
commit d07a9521c8fa3633f7206dfa52f38624d7ef11fc
2 changes: 1 addition & 1 deletion apps/docs/docs/shift-manager/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ Review the work in that worktree, or from your checkout with `git log -p <branch

Only those two projects get a worktree of your checkout. Apart from that fetch, the Lab reaches no git remote, so a coding run on a project you add yourself, even one on this repository, is refused, naming the repository, and nothing is cloned.

Open **Settings** and paste a Linear API key, and every coding run you ask for on either project can read and update Linear, as you. Each person sets their own. A run for someone who hasn't set one works without Linear and says so. For runs with nobody at the keyboard, such as a goal check or CI, `LINEAR_MCP_API_KEY` stands in for the Lab's own user until that user sets a key. An `MCP servers:` line at start says whether the Lab's own user has a key.
Open **Settings** and paste a Linear API key, and every coding run you ask for on either project can read and update Linear, as you. Each user sets their own. A run for someone who hasn't set one works without Linear and says so. For runs with nobody at the keyboard, such as a goal check or CI, `LINEAR_MCP_API_KEY` stands in for the Lab's own user until that user sets a key. An `MCP servers:` line at start says whether the Lab's own user has a key.

The coding agent is Claude Code. Sign in to Claude Code, or set `ANTHROPIC_API_KEY`, before you start. Without either, the Lab refuses to start and says so. To run the scripted coder (`stub`) instead, which writes one file and costs nothing, set `DEVFORCE_LAB_HARNESS=stub`. A `Coder:` line at start names the coder it started with. The chief of staff answers on a model of its own, so its turns need `ANTHROPIC_API_KEY` or `AI_GATEWAY_API_KEY`.

Expand Down
4 changes: 2 additions & 2 deletions apps/docs/docs/workforce/projects.md
Original file line number Diff line number Diff line change
Expand Up @@ -584,7 +584,7 @@ Put `projectWorkspaceCapability` on the harness manager's `uses`, as in the exam

A project can name MCP servers, and every coding run on the project can use their tools. MCP, the Model Context Protocol, is how an agent reaches a tool outside its checkout: an issue tracker, a docs search, a database. A run gets the project's servers however the work reached it: from a workstream, from the project's conversation, or from a task that names the project.

Three parties each decide one thing. The server running your workers decides which MCP servers exist, and their addresses. A project picks from those names. Each person sets their own key for a server, and a run uses the key of the person it works for, so it acts in that tool as them.
Three parties each decide one thing. The server running your workers decides which MCP servers exist, and their addresses. A project picks from those names. Each user sets their own key for a server, and a run uses the key of the user it works for, so it acts in that tool as them.

```ts
// the server's config, for example in a Shift Manager Lab
Expand Down Expand Up @@ -622,7 +622,7 @@ claudeCodeAgent({
});
```

Pass the same names to `defineProjectBlocks({ mcpServers: ["linear"] })`, so a project can name them. Each person's key is a record at `mcp-credentials/<server>` in their own user scope, `{ value, setAt }`. Write it from a route of your own rather than an action: an action's input is kept on its request record. A browser read of the collection shows `setAt` only. Shift Manager's [Settings](../shift-manager/settings.md) page is one such route.
Pass the same names to `defineProjectBlocks({ mcpServers: ["linear"] })`, so a project can name them. Each user's key is a record at `mcp-credentials/<server>` in their own user scope, `{ value, setAt }`. Write it from a route of your own rather than an action: an action's input is kept on its request record. A browser read of the collection shows `setAt` only. Shift Manager's [Settings](../shift-manager/settings.md) page is one such route.

### Working in a checkout you already have

Expand Down
2 changes: 1 addition & 1 deletion packages/shift-manager/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ Review the work in that worktree, or from your checkout with `git log -p <branch

Only those two projects get a worktree of your checkout. Apart from that fetch, the Lab reaches no git remote, so a coding run on a project you add yourself, even one on this repository, is refused, naming the repository, and nothing is cloned.

Open **Settings** and paste a Linear API key, and every coding run you ask for on either project can read and update Linear, as you. Each person sets their own. A run for someone who hasn't set one works without Linear and says so. For runs with nobody at the keyboard, such as a goal check or CI, `LINEAR_MCP_API_KEY` stands in for the Lab's own user until that user sets a key. An `MCP servers:` line at start says whether the Lab's own user has a key. The profile's projects and its MCP servers are in `teams/devteam/fsd-projects.mts`.
Open **Settings** and paste a Linear API key, and every coding run you ask for on either project can read and update Linear, as you. Each user sets their own. A run for someone who hasn't set one works without Linear and says so. For runs with nobody at the keyboard, such as a goal check or CI, `LINEAR_MCP_API_KEY` stands in for the Lab's own user until that user sets a key. An `MCP servers:` line at start says whether the Lab's own user has a key. The profile's projects and its MCP servers are in `teams/devteam/fsd-projects.mts`.

The coding agent is Claude Code. Sign in to Claude Code, or set `ANTHROPIC_API_KEY`, before you start. Without either, the Lab refuses to start and says so. To run the scripted coder (`stub`) instead, which writes one file and costs nothing, set `DEVFORCE_LAB_HARNESS=stub`. A `Coder:` line at start names the coder it started with. The chief of staff answers on a model of its own, so its turns need `ANTHROPIC_API_KEY` or `AI_GATEWAY_API_KEY`.

Expand Down
2 changes: 1 addition & 1 deletion packages/shift-manager/src/surfaces/Settings.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ export function SettingsView() {
<p className="text-[11px] font-semibold tracking-wider text-muted-foreground">SETTINGS</p>
<h1 className="text-base font-semibold">MCP server keys</h1>
<p className="mt-1 max-w-2xl text-sm text-muted-foreground">
A coding run on a project that names one of these servers reaches it with the key of the person the run works
A coding run on a project that names one of these servers reaches it with the key of the user the run works
for. Your keys are yours: nobody else's runs use them. Once a key is set, this page never shows it again.
</p>
</header>
Expand Down
2 changes: 1 addition & 1 deletion packages/shift-manager/teams/devteam/mcp-credentials.mts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/**
* The Lab's route for a person's own MCP server keys: read which are set, set
* The Lab's route for a user's own MCP server keys: read which are set, set
* one, clear one. What Shift Manager's Settings page writes through.
*
* GET /api/flows/mcp-credentials → { servers: [{ name, setAt }] }
Expand Down
8 changes: 4 additions & 4 deletions packages/shift-manager/test/mcp-servers.test.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/**
* A Lab's MCP servers (`openLab({ mcpServers })`): each person's key, set
* A Lab's MCP servers (`openLab({ mcpServers })`): each user's key, set
* through the Lab's own route, and a coding run on a project relayed the
* servers its project names with its owner's key.
*
Expand Down Expand Up @@ -175,7 +175,7 @@ async function allItems(lab: Lab) {

const statusTexts = (items: any[]) => items.filter((item) => item.type === "status").map((item) => JSON.stringify(item));

describe("a person's MCP server keys, through the Lab's route", () => {
describe("a user's MCP server keys, through the Lab's route", () => {
it("sets, replaces and clears the caller's own key, and answers only whether it is set and when (BR-8, BR-9, BR-10)", async () => {
const { lab } = await open();
expect(await lab.door("GET", "mcp-credentials")).toEqual({ status: 200, body: { servers: [{ name: "linear", setAt: null }] } });
Expand All @@ -187,9 +187,9 @@ describe("a person's MCP server keys, through the Lab's route", () => {
expect(read.body.servers).toEqual([{ name: "linear", setAt: set.body.setAt }]);
expect(JSON.stringify([set, read])).not.toContain("SENTINEL");

// Each user's own: the member's read says nothing of the owner's key.
// Each user's own: the other user's read says nothing of the owner's key.
expect((await lab.door("GET", "mcp-credentials", { as: "member" })).body.servers).toEqual([{ name: "linear", setAt: null }]);
expect((await lab.door("POST", "mcp-credentials/linear", { as: "member", body: { value: "member-key" } })).status).toBe(200);
expect((await lab.door("POST", "mcp-credentials/linear", { as: "member", body: { value: "other-key" } })).status).toBe(200);
expect((await lab.door("GET", "mcp-credentials")).body.servers[0].setAt).toBe(set.body.setAt);

expect(await lab.door("DELETE", "mcp-credentials/linear")).toEqual({ status: 200, body: { name: "linear", setAt: null } });
Expand Down
4 changes: 2 additions & 2 deletions packages/workforce/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1431,7 +1431,7 @@ defineFlow({ kind: "projects", actions: { ...projects.actions, ...workstreams.ac
});
```

Each person's key is `mcp-credentials/<server>` at user scope, `{ value, setAt }`
Each user's key is `mcp-credentials/<server>` at user scope, `{ value, setAt }`
(`defineMcpCredentialsCollection()`); a browser read exposes `setAt` only. Write it from a route
of your own, not an action, since an action's input is kept on its request record;
`mcpCredentialProblem(value)` says why a value can't be stored, without repeating it.
Expand Down Expand Up @@ -1908,7 +1908,7 @@ the root exports, and reaches no Node built-in.
| `defineProjectsCollection()` / `definePrivateProjectsCollection()` | The shared projects (`projects/*` at org scope) and the private ones (the same keys at each user's scope), both shared across flows and browser-readable through `expose`. Every call returns the same declaration, so they never conflict. `defineProjectFilesCollection` and `definePrivateProjectFilesCollection` declare the files; neither has a browser read. |
| `defineProjectBlocks({ mcpServers? })` | Returns `{ createProject, setRepository, setMcpServers, setBrief, readProject, listProjects, readProjectFiles, actions }`. `mcpServers` names the MCP servers a project may name; absent, none. See [Projects](#projects). |
| `projectMcpTools(servers, { operator?, env? })` / `ProjectMcpServers` / `ProjectMcpToolsResolver` | The resolver a coding harness calls once per run for its project's MCP tools, relayed through FSD's own connection with the run owner's key. See [Projects](#projects). |
| `defineMcpCredentialsCollection()` / `mcpCredentialsCapability` / `mcpCredentialProblem(value)` / `MCP_CREDENTIALS_PREFIX` | Each person's MCP server keys, `mcp-credentials/*` at user scope (client read: `setAt` only), the capability the resolving block holds, and the check a key route runs on a value. |
| `defineMcpCredentialsCollection()` / `mcpCredentialsCapability` / `mcpCredentialProblem(value)` / `MCP_CREDENTIALS_PREFIX` | Each user's MCP server keys, `mcp-credentials/*` at user scope (client read: `setAt` only), the capability the resolving block holds, and the check a key route runs on a value. |
| `checkedMcpServers(names, offered)` / `isMcpServerName(value)` | The check both project writes run on `mcpServers`. |
| `defineWorkstreamBlocks({ installation, leadFlows })` | Returns `{ openWorkstream, updateWorkstream, updateWorkstreamTool, listLeadsTool, actions }`. Each lead flow declares `workstreamOpenedEntry()` under `internal.actions[WORKSTREAM_OPENED_ENTRY]`, as the built-in `agent` flow does; one that doesn't throws. See [Projects](#projects). |
| `readProject` / `projectProgress(entries, now)` / `STALE_AFTER_MS` / `DONE_STATUS` | A project's row, entries and progress, and the progress function itself (also from `./browser`): counts by status, objectives met, the next due date, and the entries not done and unchanged for `STALE_AFTER_MS` (seven days). `"done"` is the one status with a meaning. |
Expand Down
2 changes: 1 addition & 1 deletion packages/workforce/src/projects/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
* of a project's files; `run-project.ts` for the one read of a coding run's
* project and owner; `project-workspace.ts` for the run source a coding run
* gets its files from; `project-mcp-tools.ts` and `mcp-credentials.ts` for the
* MCP servers a run gets and each person's keys for them.
* MCP servers a run gets and each user's keys for them.
*/

export {
Expand Down
2 changes: 1 addition & 1 deletion packages/workforce/src/projects/mcp-credentials.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/**
* Each person's own keys for the MCP servers a host offers.
* Each user's own keys for the MCP servers a host offers.
*
* mcp-credentials/<server> at user scope: one record per server the user set a key for
*
Expand Down
2 changes: 1 addition & 1 deletion packages/workforce/src/projects/project-mcp-tools.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
* Three parties each decide one thing. The host decides which servers exist
* and where they live (`servers`: a name, an HTTP address, and optionally the
* environment variable that seeds the operator's key). A project names some
* of them (`mcpServers` on its row). Each person sets their own key
* of them (`mcpServers` on its row). Each user sets their own key
* (`mcp-credentials/*`, at user scope), and a run uses its owner's.
*
* Per run, the resolver finds the run's project and owner with the same
Expand Down
2 changes: 1 addition & 1 deletion packages/workforce/src/projects/project-writes.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
* **MCP servers.** A project names the MCP servers its coding runs get, by the
* bare names the host offers: `defineProjectBlocks({ mcpServers })` is that
* list, and with none every name is refused (`mcp-server-name.ts`). The row
* holds names only; the address is the host's and the key each person's own.
* holds names only; the address is the host's and the key each user's own.
*/

import { handler } from "@flow-state-dev/core";
Expand Down
2 changes: 1 addition & 1 deletion packages/workforce/test/project-mcp-servers.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,7 @@ describe("a project row read by a client", () => {
});
});

describe("a person's keys read by a client", () => {
describe("a user's keys read by a client", () => {
it("show when each was set, never the value (BR-9)", async () => {
const holder = handler({
name: "holds-keys",
Expand Down
Loading