Skip to content

[Docs] The publishing rule and the staleness trigger no longer match reality #20

Description

@A13xB0

Problem

Two of the repository's own rules no longer match its state, and both bear on
what may be published.

The repository is public; CLAUDE.md says it must not be. The file states:

Private until release. Do not publish this site or enable Pages without an
explicit decision.

MeshBench/docs is public today. Either that decision was taken and never
written down, or it was not taken. The rule exists because the code repository
is private and much of its material — incidents, machine names, third-party
private repositories — cannot be published, so the boundary matters.

Related: pages/testing.md pointed readers at a board compatibility matrix in
the private repository's README.md, which a public reader cannot open. Worth
sweeping for other pointers into the private repo now the site is public.

The staleness trigger covers only the user interface. CLAUDE.md names one
trigger:

The trigger: any change under internal/ui/ in the meshcoresim repository
means the page and the screenshots for that view are checked in the same piece
of work.

That is a good rule for screenshots and it has clearly worked. But the pages
that go wrong most damagingly are not the view pages — they are the ones stating
what the physics does, and those change under internal/sim/, internal/rf/
and internal/study/, none of which trigger anything.

That gap has already produced real errors, corrected in this pass: three pages
claimed reception applies "antenna gain in the true direction to the far end"
when the engine applies the pattern's peak, and one claimed position uncertainty
propagates into downstream results when it does not. Both read as settled fact
on a public site.

Why it matters

A rule nobody has revisited is worse than no rule, because it is trusted. The
publishing rule now describes a state that does not hold, and the staleness
trigger protects the half of the site least likely to mislead someone about a
radio result.

Location

  • CLAUDE.md — the "Private until release" note and the "Keeping it true" trigger
  • pages/testing.md — the pointer into the private repository

Recommended approach

Record the publishing decision explicitly, whichever way it went, and update the
note so it describes the repository as it is.

Widen the trigger to name the directories whose behaviour the site describes —
at least internal/sim/, internal/rf/ and internal/study/ alongside
internal/ui/ — and say which pages each one bears on, so the check is as
nameable as the screenshot one. A change to how a link is judged should put
architecture.md, rf-chain.md, rf-simulation.md, waveform.md and
testing-repeaters.md in scope.

Acceptance criteria

  • CLAUDE.md describes the repository's actual publishing state, with the
    decision recorded
  • No page points a public reader at a resource only a private repository
    holds, or the pointer says access is needed
  • The staleness trigger names the code areas whose behaviour the site states,
    not only internal/ui/
  • Documentation matches current implementation
  • Links validated
  • Documentation site builds successfully

Release Impact

The publishing rule governs what may go out at all, and the trigger is what keeps
the site's physics claims true. Both should be right before the first public
release.

Activity

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

    Before First ReleaseMust be resolved before the first public releaseP1High: strongly recommended before releasedocumentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions