Skip to content

Phase 4: Move the publishable reference into docs #1340

Closed

Description

@neuromechanist

Part of epic #1336. Governed by ADR 0057. Renumbered from phase 2.

Move the material phase 1 classified as public reference into nemarOrg/docs, folding it into the
page that already covers the topic rather than adding a parallel one.

Candidates named in the epic: dataset ID bands, the release pipeline, the user flow and account
kinds, the S3 layout, the Zarr serving contract, the CLI command surface. Much of this is already
on the docs site in some form, so harmonizing removes a copy rather than adding a page. That is the
point: two copies drift, and this epic exists because they did.

Runs after phase 3 so the public/private split is already settled, and after phase 2 so anything
moved is immediately retrievable as markdown.

Acceptance

  • No topic is documented in two places; the surviving copy is on the docs site and the repo points
    at its URL.
  • Phase 1's drift guard stays green, meaning every URL referenced from this repo resolves.

Activity

  1. changed the title [-]Phase 2: Move the publishable reference into docs[/-] [+]Phase 4: Move the publishable reference into docs[/+] on Sep 13, 2026
  2. neuromechanist commented on Sep 14, 2026

    @neuromechanist
    ContributorAuthor

    Phase 4 is complete, delivered across nemarOrg/docs#38 and #1390.

    The docs half (nemarOrg/docs#38) closed the gaps that had to exist before anything could be deleted here:

    • develop/release-pipeline, a new public page. The whole topic was absent: auto-tag.yml, npm-publish.yml, sync-dev.yml, bump-version.sh and migrations:d1-check had no coverage anywhere. Public rather than gated, since every workflow file it describes is readable in a public repo and it is what an outside contributor needs to open a release PR correctly.
    • Three Zarr maintenance commands folded into admin/operations/zarr-serving: zarr:geometry-check, hallu-zarr.sh --backfill-dir-formats, and purge_non_raw_stores.py.
    • The conformance check also named in platform/zarr/format-stability, deliberately split: that the guarantees are machine-checked is a trust signal a data consumer should see, while the command and when to run it are operator material.

    The nemar-cli half landed inside #1390 rather than as a separate pass, because pointing at the URLs and rewriting AGENTS.md edit the same file and doing them twice would have churned it.

    Acceptance: no topic is documented in two places, the surviving copy is on the docs site, and the repo points at its URL. Phase 1's drift guard is green and was proven to bite on a broken pointer.


    The finding worth carrying to phase 6.

    The instinct on this phase is that the repo copy is redundant and can simply be deleted. Measured, that was false: the docs site carried 1,461 lines on Zarr against about 190 in AGENTS.md and still missed four operational facts. Page-exists is not coverage.

    And a method correction, because phase 6 repeats this classification across five more repositories: grep concepts, not code identifiers. My first pass searched for symbols (observeOnly, service_access, signup_source) and reported 12 gaps of 33 sampled, a 36 percent rate. Re-checking by concept brought it to four. Documentation describes behavior in prose and rarely names the symbol; observeOnly is fully documented in platform/zarr/access.md as "Redirects are observe-only". Acting on the symbol-only result would have meant copying implementation detail into user documentation to close gaps that did not exist.

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

    agentsdocumentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions