Skip to content

docs(workforce): an inventory row means registered, not open - #2162

Merged
jhoffner merged 2 commits into
mainfrom
docs/polish-FIX-1457
Sep 24, 2026
Merged

jhoffner merged 2 commits into
mainfrom
docs/polish-FIX-1457

Conversation

@jhoffner

Copy link
Copy Markdown
Collaborator

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

  • Every page that talks about inventory rows now says registered, not open. That covers the inventory page, the workforce README, the Agents page, the Discovery page and the Hiring-at-runtime page.
  • Reorganizes the inventory page. It now starts with what a row means. Everything that happens at boot sits in one place: the action door, the seat writer, what stops a write, 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.
  • Fixes the README's custom-channel-kind example so it matches the source's inventoryWriterActions doc comment. The channel writer goes in public actions and the seat writer in internal.actions.
  • Replaces "tree wall" with plain wording. Moves the DevTool read-only-mark note to sit next to the rule it describes: a reference is read-only.
  • Fixes the Debug vs client state page, which said "on no other condition" and then listed an exception.

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

How to review this. This change has no upstream contract: no spec, no brief, no issue that defined its scope before the work. So nothing was signed off anywhere and this PR is the only gate. The approach, the scope, and whether this earned its place at all are in scope alongside the code.

Most valuable here: whether the scope is the right scope. A change with nothing upstream constraining it is the one most likely to have grown past what was needed or stopped short of what it implied. Then the second path (the legacy shape, the null boundary, the concurrent case, the cancel path).

In scope to challenge: everything. Nothing here was settled upstream.

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 into references/" 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 (resolveEntry internals).

Flagged, not edited (code, out of scope): the header comment in packages/workforce/src/inventory/collections.ts still 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-editor cold-read sub-agent. This worker had no agent-dispatch tool. Please give the prose a cold read.

Verification: pnpm --filter @flow-state-dev/docs build exited 0. I searched the output for broken, warn and error, and the only hit was the unrelated browserslist notice. Word sweep: no remaining open right now, open channel (for inventory rows), live inventory, live seat or tree wall in apps/docs or packages/workforce/README.md.

No changeset: docs only.

🤖 Generated with Claude Code

https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz


Generated by Claude Code

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
@vercel

vercel Bot commented Sep 24, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Sep 24, 2026 7:51pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 24, 2026 7:51pm UTC
flow-state-dev-ui Ignored Ignored Preview Sep 24, 2026 7:51pm UTC

Request Review

@linear-code

linear-code Bot commented Sep 24, 2026

Copy link
Copy Markdown

FIX-1457

Copy link
Copy Markdown
Collaborator Author

docs-editor review: REVISE

I 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. packages/workforce/README.md:1555: the README gives two opposite instructions
Quote: "Any flow that spreads inventoryWriterActions will do."
Why: 27 lines later (1582), the README says "do not spread the whole return into actions". A reader who follows 1555 ends up with registerSeatsInInventory as a public action.
Fix: "Any flow carrying the writer actions will do (see Custom channel kinds)." The docs page already says it this way at inventory.md:113.

2. apps/docs/docs/workforce/inventory.md:109 and packages/workforce/README.md:1550-1551: they answer a question nobody asked
Quote: "A door that drops source does not open the seat write to other callers. The seat write fails instead, and problems names it."
Why: the sentence argues with a reviewer who was worried about security. The reader only needs to know what goes wrong.
Fix: "A door that drops source makes the seat write fail, and problems names it."

3. packages/workforce/README.md:1488-1489: two unrelated claims joined by a colon
Quote: "Nothing deletes a row: a fired seat keeps its row, and a channel's members are the ones it had when it registered."
Why: members being a copy from registration time has nothing to do with rows never being deleted. After the colon, the reader expects an example of "nothing deletes".
Fix: "Nothing deletes a row, so a fired seat keeps its row. A channel's members are the ones it had when it registered."

4. packages/workforce/README.md:825-826: a phrase used before it's defined (minor)
Quote: "the limit on which seats reach which reference applies only to the entries it names"
Why: this reads as an unexplained concept. Its definition comes 35 lines later, at "What a seat reaches".
Fix: "…and which seats reach which reference is decided only for the entries it names." Line 826 also runs past the wrap width and needs reflowing.

5. apps/docs/docs/workforce/inventory.md:74: unclear reference (minor)
Quote: "Only one of the two names an organization. openInventory writes org-scoped storage directly and takes the organization as an argument; a channel session takes its organization from the caller."
Why: "the two" makes the reader look back to work out what's meant, and "writes org-scoped storage directly" describes how it works inside.
Fix: "openInventory takes the organization as orgId. openChannels does not: each channel session takes its organization from the caller."

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

Copy link
Copy Markdown
Collaborator Author

Re the docs-editor review: all five findings are applied in 4f1a16d. Where the review gave replacement text, it is used word for word.

  1. README.md, the seat-writer line: now "Any flow carrying the writer actions will do (see Custom channel kinds)."
  2. inventory.md and README.md: now "A door that drops source makes the seat write fail, and problems names it."
  3. README.md: split into "Nothing deletes a row, so a fired seat keeps its row. A channel's members are the ones it had when it registered."
  4. README.md: "which seats reach which reference is decided only for the entries it names", with the paragraph reflowed.
  5. inventory.md: now "openInventory takes the organization as orgId. openChannels does not: each channel session takes its organization from the caller."

Also in 4f1a16d: the doc comments in packages/workforce/src/inventory/collections.ts now say "registered" instead of "open right now". That covers the file header, the key list and the channel-row comments. Only comments changed; the code behaves the same.

Verification: pnpm --filter @flow-state-dev/docs build exited 0 with no broken-link warnings. pnpm --filter @flow-state-dev/workforce typecheck exited 0.

🤖 Generated with Claude Code

https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz


Generated by Claude Code

@jhoffner
jhoffner marked this pull request as ready for review September 24, 2026 20:37
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 24, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-24T20:40:51.319207Z 4f1a16d Draft marked ready
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@jhoffner
jhoffner merged commit 777fe4d into main Sep 24, 2026
14 checks passed
@jhoffner
jhoffner deleted the docs/polish-FIX-1457 branch September 24, 2026 20:39

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment on lines +2 to +4
* 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*.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants