thehansogroup/eltrix_web
3
0
Fork 0
Code Issues 5 Pull requests Projects Releases Packages 1 Wiki Activity Actions

docs: one instruction file, and no status in files #6

Merged
jlxq0 merged 4 commits from docs-one-instruction-file into main 2026-08-26 04:48:06 +00:00
Conversation 0 Commits 4 Files changed 15 +110 -352
jlxq0 commented 2026-08-24 15:57:31 +00:00
Owner
Copy link

Closes #2.

The issue asks to rename CLAUDE.md to AGENTS.md. I wrote a new one instead,
because renaming that file would have made a false document authoritative for
both engines rather than one.

What CLAUDE.md described, and what this repository is

Jekyll-based documentation website for Eltrix, an Elixir-powered Matrix
homeserver. Deployed automatically to GitHub Pages on push to main.

This repository is Phoenix. There is no Gemfile, no _layouts, no _docs, no
_includes, and nothing deploys to GitHub Pages. Every command in it was wrong
— bundle install, bundle exec jekyll serve, JEKYLL_ENV=production — the
architecture section named files that do not exist, the front-matter schema
described a collection this repository does not have, and the dev server it
pointed at is on port 4000, which this project reserves.

A shorter AGENTS.md that is entirely true beats a long one that is half stale,
and this one was not half stale.

What is in AGENTS.md instead

The thing this repository exists for, which the old file did not mention at all:

  • The build fails if a page claims what the criteria do not back.
    EltrixSite.Capabilities names keys, never capabilities, and
    EltrixSite.Status.claim!/1 asserts each is done while the module
    compiles    . Downgrade something in eltrix_server's GOAL.md, regenerate,
    and this site stops compiling until somebody changes what the page says.
  • Why it is compile-time. Read at runtime it would degrade to a wrong page
    instead of a red build, which is the failure the design exists to prevent.
    Same reason status.json is an @external_resource: without that, a
    capability that regressed to partial would keep rendering as done out of a
    stale beam.
  • Why mix ci runs compile --force. The claims are checked while
    compiling, so a warm incremental build skips the only check this site exists
    to make. Anyone speeding CI up by dropping --force removes the gate.
  • The partial and missing lists cannot be dropped. absent/0 matters more
    than works/0 — a site that lists only finished features is not lying by
    sentence and is lying by shape. Both come from the same file and there is
    deliberately no way to render one without the other.
  • The artefacts and policies are vendored copies and can drift, and the
    policies are vendored rather than restated so the version people are held to
    is the version somebody edits.
  • Assets are built before tests because priv/static/assets is gitignored,
    which is how this site once shipped with no stylesheet and a green build.
  • The policy documents gate the first non-operator account, which puts part
    of this repository ahead of the server work rather than parallel to it.

Where the site's open work went

GOAL.md in eltrix_server carried §5, the site's criteria, and it is not in
this repository at all — so those criteria were unreachable from here. They are
now issues #3, #4 and #5 under a v1.0 milestone.

Verification

Markdown only; no Elixir file is touched. mix ci here runs
compile --force --warnings-as-errors and the test suite, neither of which this
diff can affect.

Not merged pending the cross-engine review.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SP7njJZ7ZtrMgULuXh8ddq

Closes #2. The issue asks to rename `CLAUDE.md` to `AGENTS.md`. I wrote a new one instead, because renaming that file would have made a false document authoritative for both engines rather than one. ## What `CLAUDE.md` described, and what this repository is > Jekyll-based documentation website for Eltrix, an Elixir-powered Matrix > homeserver. Deployed automatically to GitHub Pages on push to `main`. This repository is Phoenix. There is no `Gemfile`, no `_layouts`, no `_docs`, no `_includes`, and nothing deploys to GitHub Pages. Every command in it was wrong — `bundle install`, `bundle exec jekyll serve`, `JEKYLL_ENV=production` — the architecture section named files that do not exist, the front-matter schema described a collection this repository does not have, and the dev server it pointed at is on port 4000, which this project reserves. A shorter `AGENTS.md` that is entirely true beats a long one that is half stale, and this one was not half stale. ## What is in `AGENTS.md` instead The thing this repository exists for, which the old file did not mention at all: - **The build fails if a page claims what the criteria do not back.** `EltrixSite.Capabilities` names *keys*, never capabilities, and `EltrixSite.Status.claim!/1` asserts each is `done` **while the module compiles**. Downgrade something in `eltrix_server`'s `GOAL.md`, regenerate, and this site stops compiling until somebody changes what the page says. - **Why it is compile-time.** Read at runtime it would degrade to a wrong page instead of a red build, which is the failure the design exists to prevent. Same reason `status.json` is an `@external_resource`: without that, a capability that regressed to `partial` would keep rendering as `done` out of a stale beam. - **Why `mix ci` runs `compile --force`.** The claims are checked while compiling, so a warm incremental build skips the only check this site exists to make. Anyone speeding CI up by dropping `--force` removes the gate. - **The partial and missing lists cannot be dropped.** `absent/0` matters more than `works/0` — a site that lists only finished features is not lying by sentence and is lying by shape. Both come from the same file and there is deliberately no way to render one without the other. - **The artefacts and policies are vendored copies and can drift**, and the policies are vendored rather than restated so the version people are held to is the version somebody edits. - **Assets are built before tests** because `priv/static/assets` is gitignored, which is how this site once shipped with no stylesheet and a green build. - **The policy documents gate the first non-operator account**, which puts part of this repository ahead of the server work rather than parallel to it. ## Where the site's open work went `GOAL.md` in `eltrix_server` carried §5, the site's criteria, and it is not in this repository at all — so those criteria were unreachable from here. They are now issues #3, #4 and #5 under a `v1.0` milestone. ## Verification Markdown only; no Elixir file is touched. `mix ci` here runs `compile --force --warnings-as-errors` and the test suite, neither of which this diff can affect. Not merged pending the cross-engine review. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01SP7njJZ7ZtrMgULuXh8ddq
docs: one instruction file, and no status in files
All checks were successful
CI / Quality gate (pull_request) Successful in 18s
Details
CI / Build and push image (pull_request) Has been skipped
Details
7c964a81fc
 
Closes #2.

AGENTS.md is written rather than renamed. The CLAUDE.md it replaces
described a Jekyll site deployed to GitHub Pages; this repository is
Phoenix, has no Gemfile, no _layouts and no _docs, and deploys through
Forgejo. Every command in it was wrong and the architecture section
described files that do not exist.

What is in AGENTS.md instead is the thing this repository is for: the
compile-time claim gate, why it is compile-time, why `mix ci` runs
`compile --force`, why the partial and missing lists cannot be dropped,
and that the artefacts and policies are vendored copies.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SP7njJZ7ZtrMgULuXh8ddq
docs: re-vendor the privacy policy after its AGENTS.md correction
All checks were successful
CI / Quality gate (pull_request) Successful in 17s
Details
CI / Build and push image (pull_request) Has been skipped
Details
378dfe129f
 
The copy here must match eltrix_server/docs/privacy-policy.md byte for
byte — a copy that drifts is the failure vendoring exists to prevent.
Its one changed line cited CLAUDE.md as the place a logging rule lives;
that file is now a one-line import.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SP7njJZ7ZtrMgULuXh8ddq
docs: make the vendored policy's own citation true here
All checks were successful
CI / Quality gate (pull_request) Successful in 18s
Details
CI / Build and push image (pull_request) Has been skipped
Details
70c1f8b602
 
From the Codex review of #6. priv/policies/privacy-policy.md:55 says
request bodies are never logged and that this is a rule in AGENTS.md
rather than a habit. eltrix_server/AGENTS.md carries that rule; this
repository's did not — so a public-facing document served from here
pointed at a file that did not contain the rule it cited.

Fixed by adding the rule rather than editing the policy. The policy is
vendored byte for byte, and editing one copy is the drift the vendoring
exists to prevent. The rule is true of this site on its own account: it
takes form submissions.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SP7njJZ7ZtrMgULuXh8ddq
chore: remove the compile-time claim gate and the status page
All checks were successful
CI / Quality gate (pull_request) Successful in 18s
Details
CI / Build and push image (pull_request) Has been skipped
Details
893aa37b32
 
Closes #7.

Julian, 2026-08-25: the GOAL.md status mechanism goes, and this is the
half that consumed it.

Removed: EltrixSite.Status, priv/artefacts/status.json, the /status
route and its template and controller action, Capabilities.absent/0, the
four tests that exercised the status page, and `--force` from mix ci's
compile step — which existed only because the claims were checked while
compiling.

Kept: the capability cards themselves. Only the *key* passed through
Status.claim!/1; the titles and prose are content and live in
Capabilities. So the landing page still says what it said, and what is
gone is the assertion that each claim was backed. Deleting the cards as
well would have been a product change nobody asked for.

The /status page had no other source, so it goes rather than rendering
empty lists. Two paragraphs on the landing page that pointed at it are
rewritten rather than left linking to a 404.

/health used to assert the status artefact was loaded and non-empty —
the one thing that could be wrong while the process still answered. It
now reports that the process is up and its version, and claims nothing
else. A check that cannot fail would be worse than none, so it does not
pretend to have one.

The lost guarantee is issue #8, including the half that is easiest to
drop: the same page rendered what was partial and missing, from the same
source, with no way to show one list and quietly hide the other.

Verified: mix ci green — format, deps, compile --warnings-as-errors,
assets, 16 tests passed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SP7njJZ7ZtrMgULuXh8ddq
jlxq0 merged commit e60d6a8ae9 into main 2026-08-26 04:48:06 +00:00
jlxq0 deleted branch docs-one-instruction-file 2026-08-26 04:48:07 +00:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels   
bug
Something isn't working

  
documentation
Improvements or additions to documentation

  
duplicate
This issue or pull request already exists

  
enhancement
New feature or request

  
good first issue
Good for newcomers

  
help wanted
Extra attention is needed

  
invalid
This doesn't seem right

  
question
Further information is requested

  
waiting-on-julian
Blocked on Julian. The ask is in the issue.

  
wontfix
This will not be worked on

No labels
bug
documentation
duplicate
enhancement
good first issue
help wanted
invalid
question
waiting-on-julian
wontfix
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
thehansogroup/eltrix_web!6
No description provided.