Skip to content

docs: consistency pass — agent guidance, READMEs and inline docs #199

Closed

Description

@thomasfosterau

Part of the programme-wide docs and agent-guidance consistency pass (index: thomasfosterau/website#2015). This repo was reviewed read-only on main @ 9233234. Every finding below was checked against the code, scripts and workflows.

The standard in brief (the full style guide and templates will be posted on website#2015):

  • Agent guidance holds only what an agent can't infer from the code. Each rule is imperative, checkable and has its reason. Each fact has one home, and no rule is duplicated across files.
  • Root AGENTS.md sections, in order: Common pitfalls · Conventions · (Architecture) · Commands · Verification · Branches and pull requests · Work tracker · Effect · Agent sessions · Documentation surfaces. The gate list lives only in ## Verification; CONTRIBUTING.md and the PR template link to it.
  • Package CLAUDE.md sections: Boundary · Invariants · Terms. Package-local rules live only there.
  • Published package README sections: Install · Usage (a complete, compiling example) · API · License. No relative links into the repo, and no broken private-repo badges.
  • TSDoc: every exported symbol starts with a one-sentence summary. The description comes before any tag, including in module headers. Don't use @throws {@link …}, because TypeScript misparses it.
  • Generated blocks (effect-solutions, fallow setup-hooks) stay verbatim; if one is wrong, file an issue.

Verified facts that apply here:

  • effect@4.0.0-rc.118 spells the error class Schema.TaggedError<Self>()(tag, fields). TaggedErrorClass was the beta-line name.
  • pnpm 11's pnpm publish does npm trusted publishing: effect-jsonapi 0.16.1 was published that way.

Programme decisions pending with the owner that affect this issue (answers will be recorded as comments here before any edits):

  • P10: effect-jsonapi#142 is stale and conflicts with main. Proposed: close it as superseded; carry its surviving typo fix into the docs PR.

Next: one docs-only PR (Phase 2), sequenced behind the open PRs listed under Collisions. Problems where the doc is right but the code is wrong become separate issues, not doc edits.

Default branch: main @ 9233234. Coverage: all of AGENTS.md (CLAUDE.md is a symlink to it), CONTRIBUTING.md, PUBLISHING.md, SECURITY.md, .github/pull_request_template.md, .claude/settings.json, .claude/hooks/session-start.sh (comments), .claude/hooks/fallow-gate.sh (fallow-generated, header only), every workflow plus .github/actions/setup, dependabot.yml, vite.config.ts, pnpm-workspace.yaml, tsconfig*.json, docgen.json, .devcontainer. README.md: the head, the Contents list, every heading, the tail sections, and the PR #142 hunks. A script checked every Module.member reference in README.md and docs/** against the real exports. docs/: the status and pointer lines of all four notes, plus spot checks against the code. Inline docs: a script enumerated all 639 exported symbols across the 24 namespaces of . (src/index.ts) and the 8 of ./schema (src/schema.ts, a subset). All 639 have a summary, @since and @category. There are no @throws {@link} tags. The script found no declare const in any of the 232 @example blocks, and no import missing from them. I hand-read about 25 docs (ApiError, Lid, Endpoint, Handlers, Idempotency, Conformance) and both barrels' module docs.

Summary

wrong: 11 · inconsistent: 3 · bloat: 8 · missing: 4 (total 26)

The inline docs are the strongest I have seen in the programme: every export is documented, examples run under docgen, and only the src/index.ts module header (which docgen excludes) is broken. The main problems are in AGENTS.md's architecture sections, the part an agent leans on most:

  • They state an import invariant backwards: Query.ts does import Resource.ts.
  • They put ExtendedAttributes in the wrong file.
  • Their file sizes have drifted by 20–45%.

README.md describes the /schema entry point's exports wrongly (it lists Client, which is not there, and omits FlatQuery and Include). It also names a function that does not exist, Query.constrainInclude. The release and supply-chain rationale is written out four times (release.yml, PUBLISHING.md, SECURITY.md, CONTRIBUTING.md). The gate list exists in four places in three different orders. PR #142 is stale (opened 15 days ago, conflicting, and its hunks target text the rc.118 migration and the reformat have since rewritten). It should be closed in favour of the Phase 2 README edit.

Findings

ID Sev File:line Problem Proposed wording / deletion Rationale (style-guide rule, evidence)
R-1 wrong AGENTS.md:41 Claims "Query.ts does not import Resource.ts". It does: src/Query.ts:86 value-imports allTargets, attributeKeys, filterable, includePaths from ./Resource.js. The real cycle-avoidance invariant is the reverse direction. See Appendix A, paragraph 1. Rule 7 (verified); rule 1 (an import boundary is exactly what an agent needs). Evidence: src/Resource.ts:48-54 imports only Document, Filter, internal/operators, Relationship and Sort.
R-2 wrong AGENTS.md:45 The line counts have drifted: "~2900", "~1300" and "~2950" are now 3451 (Resource.ts), 1898 (Query.ts) and 3580 (Endpoint.ts). Drop the counts: "src/Resource.ts and src/Query.ts carry almost all the conditional/mapped-type work; src/Endpoint.ts is large mostly from repetition …" Rule 7; [CC-BP] "exclude frequently changing info". Evidence: wc -l.
R-3 wrong AGENTS.md:47 "Endpoint.ts's ExtendedAttributes" is wrong: ExtendedAttributes is src/Resource.ts:2977. The local AsFields copies are in src/Query.ts:1536 and src/Atomic.ts:289 (the original is src/Resource.ts:932). "AsFields<T> (src/Resource.ts, with private copies in src/Query.ts and src/Atomic.ts) is the recurring escape hatch:" Rule 7.
R-4 wrong AGENTS.md:13 Says the staged-rollout rules sit at warn "with their counts". vite.config.ts:83-85 counts only 5 of the roughly 45 warn rules. The bullet also repeats CONTRIBUTING.md:57 and the vite.config comment. "vp lint runs the full Effect preset with a staged rollout. The warn tier in vite.config.ts is debt, not headroom: fix any new site, and when a rule's count reaches zero flip it to error and delete its line." Delete CONTRIBUTING.md:57's second sentence and link here instead. Rules 6, 7.
R-5 wrong README.md:25 "/schema re-exports Client, Document, Filter, Relationship, Resource, Sort and MEDIA_TYPE" is wrong. src/schema.ts exports Document, Filter, FlatQuery, Include, Relationship, Resource, Sort and MEDIA_TYPE, and its own header (src/schema.ts:36-43) says Client is outside the tier. (overlaps #142) "/schema re-exports Document, Filter, FlatQuery, Include, Relationship, Resource, Sort and MEDIA_TYPE — the modules whose import graph is effect alone." Rule 7; [README] "must not contain broken" facts.
R-6 wrong README.md:31 Query.constrainInclude does not exist. The function that fails with UnsupportedIncludePath / UnsupportedIncludeDepth is Query.validateIncludePaths (src/Query.ts:1017). (overlaps #142) Replace Query.constrainInclude with Query.validateIncludePaths. Rule 7; checked by script over all Module.member refs.
R-7 wrong src/index.ts:4-45 The module doc hovers on every root import, and it has four faults. (1) It cites "the convention of effect and @effect/platform", but @effect/platform does not exist in v4. (2) The import list omits 7 of the 24 namespaces (Assemble, FlatQuery, MediaType, Negotiation, Registry, ResourceHandlers, ServerErrors). (3) The sample uses Schema without importing it. (4) The sample references an undefined Comment. docgen excludes src/index.ts (docgen.json), so nothing catches this. Replace lines 4-45 with: "Every module is exported as a namespace from the package root. Import what you use: `import { Endpoint, Group, Query, Resource } from "@thomasfosterau/effect-jsonapi"`. The schema-only subset is @thomasfosterau/effect-jsonapi/schema." Keep @packageDocumentation and @since. Inline-docs rule "@example must be correct" (examples are copied); [PE] examples are followed closely.
R-8 wrong docs/filter-grammar.md:10, :304, :541, :548 Four stale facts. (1) :10 says "#85 (the canonical self string) follows", but #85 closed on 2026-09-03 and Query.canonical / canonicalPairs / serialise ship (src/Query.ts:1785-1893). (2) :304 src/Middleware.ts:83 points at the tracing docs; the profile handling is at around :144-152. (3) :548 src/internal/codecs.ts:115-147 is the Sort codec; nest is at :152-168. (4) :541 README.md:705-707 points at the success-override section. :10 → "… are in the package, as is #85 (the canonical self string, Query.canonical)." :304 → "(src/Middleware.ts, the profile branch)". :548 → "(codecs.ts's nest)". :541 → "(README, Query parameters)". Drop the line numbers. Docs rule (fix factual errors that mislead today); rule 7.
R-9 wrong docs/conformance.md:5 "31 rules across two tiers" is wrong. The kit has 36: 31 in src/internal/conformance/spec.ts:1414 and 5 in profile.ts:489. The 8 gaps figure is correct. "Status: v1 implemented. 36 rules (31 spec, 5 profile), eight declared coverage gaps." Or drop the counts in favour of "see Conformance.rules / Conformance.gaps". Rule 7; counted from the rule arrays.
R-10 wrong .claude/hooks/session-start.sh:58, :139, :172; pnpm-workspace.yaml:34 Says "pnpm run docgen", but package.json has no docgen script; docgen is a vp task (vite.config.ts:234). :172 says "masquerade as trunk breakage", but the default branch is main. pnpm run docgen → vp run docgen (3 sites); "trunk breakage" → "breakage on main". Rule 7; vocabulary (default branch by its real name).
R-11 wrong CONTRIBUTING.md:137 The template checklist gives the CI order as "vp check → vp run check → vp run -r test:unit → vp run build → vp run docgen → pnpm audit". ci.yml:65 runs vp run build first so the check graph gets a cache hit (CONTRIBUTING.md:102 has the order right). "… task-cache restore, vp run build (on the toolchain Node, before the matrix switch) → vp check → vp run check → vp run -r test:unit → vp run docgen → pnpm audit --audit-level high …" Rule 7. This file is the template other repos copy, so the wrong order propagates.
R-12 inconsistent src/ApiError.ts:332, Client.ts:870/900/1084/1111/1266, Negotiation.ts:211, Resource.ts:743/769, ServerErrors.ts:52/64/75/87/100/121/407 16 @category tags fall outside the vocabulary CONTRIBUTING.md:74 fixes: readers (5), catalogue (6), utilities (2), predicates, mapping, encoding. docgen renders utils and utilities as separate headings. utilities→utils; predicates→guards; readers→accessors; encoding/mapping→utils; catalogue→errors. Alternatively, add catalogue and readers to the CONTRIBUTING list if they are wanted. Inline-docs rule "keep repo-required tags", applied consistently.
R-13 inconsistent AGENTS.md:84-117 (H2 names) The H2 names differ from the template: "Branch model", "Working a dispatched issue" and "PR management" (template: one ## Branches and pull requests plus ## Work tracker), and "Effect best practices" (template: ## Effect). There is no ## Conventions, ## Agent sessions or ## Verification-first ordering. Rename and fold as in "Structure vs templates" below. Move "Working a dispatched issue" bullets into ## Work tracker. Merge "Branch model" and "PR management" into ## Branches and pull requests. Templates.md; shared vocabulary.
R-14 inconsistent README.md:11-15 Install section uses npm install …, while the template and the programme say pnpm. It states the peer range but not how to install the peer with pnpm. (overlaps #142) "bash\npnpm add @thomasfosterau/effect-jsonapi effect\n\neffect is a peer dependency (>=4.0.0-rc.118)." Keep the Node line once D-1 is settled. Templates.md "Library README" ## Install.
R-15 bloat AGENTS.md:3-5 Two preamble paragraphs (about 230 words) give lineage and history: which sibling repos share the standard (the list is incomplete: effect-web and effect-email also copy it), which "pieces only this repository had", and "personal style preferences live in user memory". An agent cannot act on any of it. Replace lines 3-5 with: "CLAUDE.md is a symlink to this file. @thomasfosterau/effect-jsonapi is a publishable library (entry points . and ./schema), consumed by the website, gardeneria and preferenceflow apps. Its toolchain is the programme's library standard (checklist: CONTRIBUTING.md), with deviations listed at the top of pnpm-workspace.yaml. A gardeneria #NNN citation in a copied comment names an issue in that app, not this tracker." [CC-BP] "would removing this cause mistakes?"; rule 1.
R-16 bloat AGENTS.md:9-10 Line 9 restates what catalogMode: strict enforces and what the pnpm-workspace.yaml header already says. Line 10 restates the @effect/tsgo catalog comment (pnpm-workspace.yaml:38-52) in full. :9 → "Versions live only in the pnpm-workspace.yaml catalog (catalogMode: strict); after editing it run pnpm install and commit pnpm-lock.yaml — a stale lockfile fails CI with ERR_PNPM_LOCKFILE_CONFIG_MISMATCH." :10 → "@effect/tsgo, @typescript/native and vite-plus bump as a set — read the comment on @effect/tsgo in pnpm-workspace.yaml first; an unsupported pairing fails pnpm install." Rule 10 (tooling enforces it, so keep only the error string); rule 6.
R-17 bloat AGENTS.md:16-29 vs CONTRIBUTING.md:72; AGENTS.md:55-59 vs CONTRIBUTING.md:83 The docgen example rules (self-contained, no declare const, must run) and the type-level-test rule are each stated in full in both files. Keep them in AGENTS.md. Cut CONTRIBUTING.md:72 to "An @example for the principal APIs — it must compile and run under vp run docgen; see AGENTS.md." Cut :83 to a link. Rule 6 (one home per fact).
R-18 bloat AGENTS.md:72-82, :110-113; CONTRIBUTING.md:23-31, :39-49, :104-114; .github/pull_request_template.md The gate list is written four times. The orders differ: AGENTS Verification puts build before docgen with no fallow; CONTRIBUTING Pre-PR adds fallow audit and a changeset; ci.yml runs build first. AGENTS keeps ## Commands (one line each) and ## Verification (the ordered pre-push list, including fallow audit --base origin/main and the changeset). CONTRIBUTING's "Getting started" step 3 and "Pre-PR checklist" link to it. The PR template keeps its checkboxes. Rule 6; [CC-MEM] contradictions make Claude "pick one arbitrarily".
R-19 bloat PUBLISHING.md:11, :13, :15; SECURITY.md:13-15; CONTRIBUTING.md:138; release.yml:29-95 The pnpm-publish/OIDC rationale, verify-deps-before-run, run-prepare: "false" and the provenance behaviour are each explained three or four times. Keep the workflow comments (they explain the pins in place). Make SECURITY.md the one prose home. Replace PUBLISHING.md:11-15 with: "The publish step is pnpm publish --ignore-scripts from the protected release environment via npm trusted publishing (OIDC); no provenance while the repository is private. Why each setting is what it is: SECURITY.md." CONTRIBUTING.md:138 keeps only the file list. Rule 6.
R-20 bloat README.md:5, :44-50, :52-97, :1899-1911 Several blocks repeat other content. :5: three badges (a CI badge for a private repo renders broken on npm; the license badge repeats ## License). :44-50: an import snippet and a "Status" note that repeat :15. :52-97: a hand-kept Contents list, which already misses 6 H3s (Nullable primary data, Reusing & extending resources, Reading error documents, The client helpers…, Declaring filterable and sortable attributes, The canonical query string). :1907: a ## Links section. (overlaps #142, which deletes :44-50) Delete :5 (or keep only the npm badge), :44-50, :52-97 and :1907-1911. Docs rule "no badges unless live status"; style guide drops the ToC (npm/GitHub render an outline).
R-21 bloat README.md:17-33 "Importing without the HTTP surface" (17 lines) sits before Overview and Quick start, ahead of anything a first-time reader needs. Most of it repeats src/schema.ts:1-44. (overlaps #142) Move it after Quick start as ### The schema-only entry point. Keep :19-25 (with R-5's fix). Replace :27-33 with "Which modules are in the tier, and why Query is not: see the /schema module doc." Templates.md order (what, install, usage, API); rule 6.
R-22 bloat CONTRIBUTING.md:3, :116-127, :149-155 Contains generic boilerplate: "Thank you for your interest…", "Commit messages" and "Pull request process" (which repeat the Changesets section and AGENTS), and "Reporting issues" / "Feature requests" in a private repo with no issue templates. Delete :116-127 and :149-155. :3 → "Setup, commands and checklists; conventions are in AGENTS.md." Docs rule "no padding"; rule 6.
R-23 missing AGENTS.md (no section) AGENTS.md never mentions the SessionStart hook. CONTRIBUTING.md:33 describes it, but AGENTS.md doesn't say what it provisions or that nothing needs credentials (only Verification :113 hints at the latter). Add ## Agent sessions: "The SessionStart hook (.claude/hooks/session-start.sh, also the devcontainer's postCreateCommand) runs vp install --frozen-lockfile (which applies the tsgo patch) and links vp, tsx and fallow onto PATH. It hydrates no secrets; every gate runs offline. A PostToolUse hook runs vp fmt on each edited file, and a PreToolUse hook runs the fallow gate before git commit / git push." Then cut CONTRIBUTING.md:33 to a link. Rule 8; templates.md ## Agent sessions.
R-24 missing AGENTS.md:101-108 PR management omits two things. It has no changeset rule (only the Commands line :80) and no "never publish or version by hand; the owner merges the Version Packages PR". The sibling repos (components, prosekit-utilities, effect-web, effect-auth) all state both. Add: "- A PR that changes published behaviour carries a changeset. Never publish or version by hand; the owner merges the "Version Packages" PR (PUBLISHING.md)." Shared vocabulary; [AGENTS] PR instructions.
R-25 missing AGENTS.md:113 The Verification list omits fallow audit --base origin/main and the changeset check, both of which are in CONTRIBUTING.md:111-112. It doesn't say that docgen must run after build or what to do when a gate cannot run. "The pre-push run, in order: pnpm install --frozen-lockfile, vp check, vp run check, vp run -r test:unit, vp run build, vp run docgen, fallow audit --base origin/main. None needs a credential, database, browser or Docker. If one cannot run, say so in the PR body." [CC-BP] "give Claude a way to verify its work"; rule 2.
R-26 missing AGENTS.md:115-117 The Effect section has no caveat for the installed version. The code imports effect/http-api and effect/http (src/Endpoint.ts:80, src/Client.ts:105). Sibling AGENTS files and older guides still say effect/unstable/httpapi (effect-forms) or @effect/platform, and this repo's own src/index.ts:5 says @effect/platform. Append: "In effect@4.0.0-rc.118 the HTTP API modules are effect/http-api and effect/http — not effect/unstable/httpapi, and there is no @effect/platform. When effect-solutions and the code disagree, the code (and node_modules/effect/src) wins." Keep IMPORTANT only on this section. Templates.md ## Effect "installed-version caveats"; rule 5.

Appendix A — AGENTS.md:41 replacement (R-1)

Import direction is one-way: Resource.ts imports neither Query.ts nor Endpoint.ts. Query.ts uses Resource.ts's allow-list helpers (allTargets, attributeKeys, filterable, includePaths) and Endpoint.ts uses both. Reversing any edge creates a cycle. Query.ts is generic over the structural shape a resource definition produces rather than over the Resource type, so when tracing "where does this type come from", follow the resource definition through generic parameters, not through import statements.

Decisions needed from the owner

  • D-1. Supported Node range (the docs are inconsistent because the config is). package.json engines.node: ">=22" and README.md:15 say "Node.js 22 or newer is required". But ci.yml:36 tests the library on 20.x, and the main ruleset requires the (20.x) check. Options:

    • (a) Support 20 for consumers. Drop or relax engines (it is published, so consumers on 20 get engine warnings) and have the README say "runs on Node 20+; developing needs 22".
    • (b) Drop 20.x from the matrix and the ruleset.

    I recommend (a) if any consumer still runs Node 20 (Workers are unaffected); otherwise (b). This becomes a separate issue, not a doc edit.

  • D-2. PR docs: refine README for clarity and consistency #142 (owner, opened 2026-09-16, single commit d4ea8eb, no body, mergeable_state: dirty). Its base 1670eeb predates the whole-repo vp fmt reformat (chore: migrate to the Vite+ library standard, and fold this repo's docgen, type-level tests, Effect canary and OIDC release into the shared library template #175) and the rc.118 migration, which rewrote the lines it edits (the beta.104 Status note it deletes is now an rc.118 note; the hard-wrapped prose it unwraps is already unwrapped). What survives of its intent:

    • the "implement" typo fix (README.md:3, still present);
    • softening "trivial to comply … invariantly";
    • deleting the import snippet and Status note (= R-20);
    • shortening section titles.

    Recommendation: close docs: refine README for clarity and consistency #142 as superseded, and have the Phase 2 README PR carry the typo fix plus whichever tone edits the owner still wants.

  • D-3. README length (1911 lines). Options:

    • (a) Keep README as the single npm API reference. Delete the ToC (R-20) and add a short ## API table of the 24 namespaces.
    • (b) Move §5 "The server skeleton" and "Query parameters" into docs/guides/.

    I recommend (a). The README is the reference consumers read on npm, and its depth is earned. What's missing is the one-glance module index (only src/index.ts has it).

  • D-4. Home of "The library template checklist" (CONTRIBUTING.md:129-147, 19 lines of programme-level procedure inside one library's contributor guide). Options:

    • (a) Keep it here as the canonical copy that the other library repos link to.
    • (b) Move it to a programme-level home, such as an issue on website#2015.

    I recommend (a), renaming it ## Library template (programme standard) and pinning the gate order to ci.yml (R-11). But the coordinator should settle whether other repos point here.

  • D-5. One prose home for release/supply-chain rationale (R-19): SECURITY.md (recommended) or PUBLISHING.md.

Structure vs templates

Root AGENTS.md (137 lines, under the 200-line limit). Current H2s:

  1. Common pitfalls
  2. vp run docgen executes your examples
  3. Architecture: everything derives from Resource.make
  4. Where the type machinery lives
  5. Type-level tests: test/*.types.ts
  6. Wire format: flat vs. nested query schema
  7. Commands
  8. Work tracker
  9. Branch model
  10. Working a dispatched issue
  11. PR management
  12. Verification
  13. Effect best practices
  14. Documentation surfaces
  15. (fallow-generated) Fallow local gate
  16. (fallow-generated) Fallow task map

Deviations from the template:

  • No package table. Correct: this is a single-package repo.
  • Sections 2–6 are repo-specific architecture and traps. They are legitimate and the most valuable content in the file. The template should allow either a ## Architecture H2 (holding 3–6 as H3s) or have them folded under ## Common pitfalls. I recommend ## Architecture with H3s: "Everything derives from Resource.make", "Type machinery", "Type-level tests", "Flat vs nested query schema"; and the docgen section as a ## Conventions entry.
  • No ## Conventions. exactOptionalPropertyTypes sits in pitfalls, and the vite-plus/test import rule and .js relative-import extensions are only in CONTRIBUTING/code. Note that this repo uses .js extensions in relative imports, while prosekit-utilities and effect-web use .ts. That is a legitimate difference, but a one-line statement would help agents who move between repos.
  • Naming. Branch model + Working a dispatched issue + PR management should become ## Branches and pull requests + ## Work tracker. Effect best practices should become ## Effect.
  • Missing sections. ## Agent sessions is missing (R-23).
  • Order. Verification should follow Commands.

Package CLAUDE.md: none (single package). Correct.

README.md H2s: Installation (H3: Importing without the HTTP surface); Overview; Contents; Quick start; 1. Resources — the single source of truth; 2. Errors; 3. Endpoints & groups; 4. Handlers; 5. The server skeleton; Query parameters; Spec compliance, by construction; Proving it: the conformance kit; Examples; Metadata; Limitations; Contributing; License; Links. Deviations from templates.md:

  • Installation should be Install, and the Install section uses npm (R-14).
  • Overview + Quick start should be Usage. Quick start fits the "smallest complete working example" slot well, but Overview's bullets are partly marketing.
  • ## API is missing (D-3).
  • Contents and Links are extra (R-20).

Legitimate additions: the numbered reference sections, Spec compliance, Conformance kit, Limitations (a template ## Compatibility-style optional section). The Contributing link is fine for a single-package repo. A 1911-line reference is legitimate for this library (D-3).

CONTRIBUTING.md H2s: Development setup; Development workflow; Code style; Documentation; Testing; Changesets; Git hooks; CI expectations; Pre-PR checklist; Commit messages; Pull request process; The library template checklist; Reporting issues; Feature requests; Scope; License. These overlap AGENTS heavily (R-17, R-18, R-22).

PUBLISHING.md: The release flow; Maintainer setup (one-time). SECURITY.md: Reporting a vulnerability; Supply-chain hardening; Release pipeline. No template exists for these yet; they match the sibling library shape.

Collisions

  • docs: refine README for clarity and consistency #142 ("docs: refine README for clarity and consistency"; owner; open since 2026-09-16; conflicting) touches README.md. It collides with R-5, R-6, R-14, R-20 and R-21, and directly with R-20's deletion of README.md:44-50, which docs: refine README for clarity and consistency #142 also deletes. Recommendation in D-2: close it as superseded and fold the typo fix into Phase 2.
  • No other open PR touches AGENTS.md, CONTRIBUTING.md, PUBLISHING.md, SECURITY.md, docs/**, .claude/**, src/index.ts or the @category sites.

Generated by Claude Code

Activity

  1. thomasfosterau commented on Oct 1, 2026

    @thomasfosterau
    OwnerAuthor

    Owner decisions (2026-10-01)

    The owner answered the programme-level decisions listed above. Phase 2 follows these:

    • P10, effect-jsonapi#142: approved to close it as superseded. Its README typo fix moves into the docs PR.
    • P7 (programme-wide), GitHub MCP sentence: agreed. Use: "Use the gh CLI for GitHub operations, even when GitHub MCP tools are available."
    • Repo-specific decisions: each recommendation in this issue's "Decisions needed" section is accepted. Wherever a doc is right but the code is wrong, the fix goes in a separate issue rather than a doc edit.

    Next: a docs-only PR, sequenced behind the open PRs listed under Collisions.


    Generated by Claude Code

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions