Repository navigation
docs(workforce): an inventory row means registered, not open - #2162
Conversation
The inventory page and the workforce README described inventory rows as "one row per open channel" / "what is open right now". A row records that a seat or channel was registered in the organization; nothing deletes one. Make every page say so, and polish the pages the workforce release touched: - inventory page: retitle to "Inventory", lead with what a row means, group the boot-time behaviour (door, seat writer, refusals, problems, re-runs) under the boot section, fold the duplicate "what is written" list and seat-channels example into the reading section, point at the hired roster and the DevTool tab - workforce README: same meaning fix; fix the custom-channel-kind example, which spread the boot-only seat writer into public actions - documents-on-disk / workers-on-disk / README: replace the undefined "tree wall" term with plain wording; move the DevTool read-only mark note next to the reference read-only rule it describes - debug-vs-client-state: the read-only mark section no longer contradicts its own projected-collection exception - agents / discovery / durable-hire: drop "open" and "live" wording for inventory rows Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
docs-editor review: REVISEI read the changed pages at the branch head as someone who doesn't know how the feature was built. I didn't read the spec, the PR body or any implementation. Most of the changes read cleanly. The em-dashes in the README inventory section are gone, and "registered, not open" is stated plainly. Three things would still trip a reader. 1. 2. 3. 4. 5. Suspected inaccuracies: none. I didn't check facts. Offered context declined: none was offered. Generated by Claude Code |
- README: the seat-writer line no longer tells readers to spread inventoryWriterActions (contradicted Custom channel kinds) - inventory page + README: state what dropping `source` does, without the security aside - README: split "nothing deletes a row" from the members-copy point - README: link "which seats reach which reference" to What a seat reaches - inventory page: name openInventory and openChannels directly - collections.ts: header and channel-row doc comments say "registered", not "open right now" (comment only, no behaviour change) Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
|
Re the docs-editor review: all five findings are applied in 4f1a16d. Where the review gave replacement text, it is used word for word.
Also in 4f1a16d: the doc comments in Verification: 🤖 Generated with Claude Code https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz Generated by Claude Code |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4f1a16db8c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| * The inventory's three org-scoped collections — what was registered in this | ||
| * organization, as opposed to what the tree declares. A row means *was | ||
| * registered*, not *is open now*. |
There was a problem hiding this comment.
Correct the remaining public inventory descriptions
This comment now correctly defines inventory rows as historical registrations, but the package header at packages/workforce/src/index.ts:37-49 and the inventory barrel at packages/workforce/src/inventory/index.ts:2 still describe them as holding “what is actually open.” Because rows are never deleted, those public source/IDE descriptions expose contradictory contracts and can lead consumers to treat stale seats or channels as live; update the remaining exported-surface documentation to use the registration semantics too.
AGENTS.md reference: AGENTS.md:L50-L50
Useful? React with 👍 / 👎.
The problem
The Workforce docs told readers that an inventory row means a seat or channel is open right now. The page was titled "Live Inventory", and the README table listed "one row per open channel". That is wrong. A row only records that a seat or channel was registered in the organization, and nothing ever deletes one. So a fired seat or a channel that is gone still shows up. A reader who trusted the docs would treat old rows as current, which is exactly the mistake the DevTool's "Registered" labels are there to prevent. Two pages also used a term they never define ("the tree wall"). The README's example for custom channel kinds also put the boot-only seat writer into public actions, which the same README says not to do.
What this does
problems, and running it twice. A duplicated "what is written" list and a repeated code example are folded in. The page now links to the hired roster and to the DevTool's Inventory tab.inventoryWriterActionsdoc comment. The channel writer goes in publicactionsand the seat writer ininternal.actions.What's asked of you
Nothing to decide. Review it and merge if you're happy with it. The sidebar label changes from "Live Inventory" to "Inventory". The URL doesn't change.
Parts worth reviewing closely
apps/docs/docs/workforce/inventory.md. Every fact on the old page should still be there after the move. The "what openInventory writes" list was dropped because the key table and the row shapes already say the same thing.packages/workforce/README.md, "Custom channel kinds". This changes an example's behavior, not just its wording. Checked againstpackages/workforce/src/channel/channel-flow.ts.Links: epic FIX-1457 wrap (docs polish). Draft, and a human decides whether to merge.
How to review this
On an editorial pass, the highest-value question is whether anything changed meaning rather than presentation: a caveat dropped, an API detail lost, an example quietly altered. The other is whether the new arrangement really navigates better than the old one.
Everything else: moved / merged / cut, flags, verification
Scope: the docs paths changed by #1958, #2039, #2051, #2065, #2066, #2133, #2147, plus pages that repeated the same inventory claim (agents, discovery, durable-hire).
Moved / merged: inventory "What stops a write", "What lands in
problems" and "Running it twice" now sit under "Wiring the boot". "Listing one seat's channels" is now under "Reading the inventory" and no longer repeats the handler. "Nothing is deleted" is folded into the new lead paragraph. The DevTool read-only note moved from "Moving a document intoreferences/" to "Letting a model read a document".Cut: the "What openInventory writes" list on the site page, which duplicated the key table and row shapes. Mechanism prose in the README (
resolveEntryinternals).Flagged, not edited (code, out of scope): the header comment in
packages/workforce/src/inventory/collections.tsstill opens with "what is actually open right now" and "which channels are open". Its own last paragraph says a row means registered. Worth a follow-up so the code comment agrees with the docs.Not run: the
docs-editorcold-read sub-agent. This worker had no agent-dispatch tool. Please give the prose a cold read.Verification:
pnpm --filter @flow-state-dev/docs buildexited 0. I searched the output forbroken,warnanderror, and the only hit was the unrelated browserslist notice. Word sweep: no remainingopen right now,open channel(for inventory rows),live inventory,live seatortree wallinapps/docsorpackages/workforce/README.md.No changeset: docs only.
🤖 Generated with Claude Code
https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
Generated by Claude Code