Skip to content

Phase 6: Apply the pattern to the other repos #1378

Closed

Description

@neuromechanist

Part of epic #1336. Governed by ADR 0057.

nemar-cli goes first because it is the biggest, and whatever pattern it settles becomes the
pattern for the rest. This phase applies that pattern outward.

Repos in scope

Each has agent-facing material and at least some of it is admin-only under ADR 0057's recipe test:

  • nemarOrg/website (public): AGENTS.md plus a .context/ tree including 14+ ADRs
  • nemarOrg/nemar-observability (public): AGENTS.md, CLAUDE.md, .context/, .rules/
  • nemarOrg/docs (public): its own AGENTS.md, already partly corrected in phase 0
  • nemarOrg/nemar-tools (private): already private, so the source split does not apply, but the
    retrieval contract does

Scope

  • Run phase 1's classification rule over each repo's agent files.
  • Move what the rule marks admin-only into the private content repo phase 3 creates.
  • Rewrite each AGENTS.md to hard rules plus docs URLs, carrying the same escalation instruction
    phase 5 writes: a non-admin who hits an admin-adjacent problem tags the admin team rather than
    being stuck.
  • Leave ADRs where they are. They are binding decisions about the code they sit next to, and the
    docs link them at their public GitHub paths.

Note

nemar-observability commits CLAUDE.md, which the owner's standing convention keeps gitignored.
Worth resolving while touching that repo, but it is not this epic's decision to make.

Activity

  1. neuromechanist commented on Sep 14, 2026

    @neuromechanist
    ContributorAuthor

    Correction: this issue's scope still assumes a design ADR 0059 replaced.

    The scope above says to "move what the rule marks admin-only into the private content repo phase 3 creates." Phase 3 creates no such repo. ADR 0059 settled on one docs repo, private at source and public at the URL, precisely to avoid a second content repo, a build-time content pull, a content credential, and a degradation path for when the private half is unreachable.

    So for each repo in scope, admin-only material moves into nemarOrg/docs under /admin/, where the existing gate gives it exactly the protection nemar-cli's does. Everything else in this phase stands.

    Two other things this phase should now carry, both learned after it was written:

    1. Retrieval is already solved for agents. Phase 2 gave every docs page a .md mirror and phase 3 added nemar admin docs <path...>, which trades a CLI API key for a short-lived docs-scoped session (Phase 3 (part 1): the credential exchange, so an admin can read gated docs without a browser #1384). So the per-repo AGENTS.md rewrites can point at URLs and name a command that actually retrieves them, rather than describing an aspiration.

    2. nemarOrg/docs is listed as public here. It is public today and becomes private at source in phase 3, so by the time this phase runs that line is wrong. Its own AGENTS.md still needs the pass.

  2. neuromechanist commented on Sep 14, 2026

    @neuromechanist
    ContributorAuthor

    Scope survey, 2026-09-14. The repo list in this issue is wrong in both directions.

    Measured against the live org rather than from memory:

    repo visibility AGENTS.md CLAUDE.md .context/ .rules/
    website public 32.8 KB 3.1 KB 8 9
    nemar-citations public 20.3 KB ? ? ?
    docs private 15.6 KB 374 B 5 7
    nemar-observability public 10.0 KB 374 B 5 8
    nemar-infisical private 5.1 KB ? ? ?
    orcid-mock private 3.4 KB ? ? ?
    nemar-tools private none none none none

    nemar-tools has no agent files at all. Not an access problem: its root lists .gitignore, README.md, docs/, requirements.txt, scripts/, templates/ and nothing else. There is nothing here to reclassify or rewrite. Either drop it from scope or make the task "create one", which is a different piece of work and should be decided rather than assumed.

    Three repos with agent files are missing from scope, and one of them is significant: nemar-citations carries a 20.3 KB AGENTS.md and is public, so ADR 0057's source-split rule applies to it exactly as it did to nemar-cli. nemar-infisical and orcid-mock are already private, so the split does not apply, but the retrieval contract and the escalation instruction do.

    website is the real work. At 32.8 KB its AGENTS.md is larger than nemar-cli's was before phase 5 cut it from 669 lines to 313, and it carries 8 .context/ entries and 9 .rules/ entries on top.

    One method correction carried from phase 4, because this phase repeats that exercise five more times: classify by grepping CONCEPTS, not code identifiers. A symbol-only search reported three times as many documentation gaps as were real, because documentation describes behavior in prose and rarely names the symbol. Acting on it would mean copying implementation detail into user documentation to close gaps that do not exist.

    Suggested order, largest leverage first: website, then nemar-citations, then docs, then nemar-observability, then the two small private ones.

  3. neuromechanist commented on Sep 14, 2026

    @neuromechanist
    ContributorAuthor

    Phase 6 is complete. Six repositories, six merged pull requests.

    repo PR before after
    website nemarOrg/website#332 486 286
    nemar-citations nemarOrg/nemar-citations#215 221 254
    docs nemarOrg/docs#40 115 140
    nemar-observability nemarOrg/nemar-observability#43 123 149
    nemar-infisical nemarOrg/nemar-infisical#1 93 119
    orcid-mock nemarOrg/orcid-mock#2 50 76

    Plus nemarOrg/docs#39, which documented the website release process before any of it was deleted from website.

    The scope in this issue was wrong in both directions and was corrected first. nemar-tools was listed and has no agent files at all; it has since been archived as stale (last push 2026-02-10, every reference to it documentary, its Zenodo flow superseded by EZID per ADR 0007). nemar-citations, nemar-infisical and orcid-mock had agent files and were missing from the list. nemar-citations mattered most: public, and the source-split rule applied to it in full.


    Only one repository got shorter, and that is the honest outcome rather than a shortfall.

    The pattern is "do not keep a second copy of the documentation site", not "make the file shorter". website was the only one carrying a real second copy, and it lost 200 lines. The other five describe their own systems, so applying the rule faithfully meant adding the two things they lacked: a retrieval contract and an escalation instruction. A pass that had cut them to look consistent would have destroyed information.

    Two refinements this phase added to the pattern.

    A section can mix material that moves with material that stays. website's deploy and staging sections looked like 133 lines to relocate, but the parts missing from the docs site turned out to be that repo's own code symbols (__EDGE_CACHE_NAMESPACE__, applySecurityHeaders, isNoindexHost, getCrossHostRedirect). Those are implementation detail; moving them would have pushed website internals onto a public documentation site. They stayed, and only the operational half became a pointer.

    Classify by grepping concepts, not code identifiers. Carried from phase 4, where a symbol-only search reported three times as many documentation gaps as were real.

    One consequence of the phase 3 flip surfaced here and was fixed. docs.nemar.org serves public pages from a repository that is now private, so a reader who spots an error cannot file against its source. The site footer now carries "Report a problem", pointing at this repository's public issue template, and support@nemar.org for a reader with no GitHub account. Both addresses already existed on the site; no new infrastructure was added.

    Epic #1336 has no phases left.

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