Skip to content

docs: align documentation with actual repo state - #35

Merged
iap merged 6 commits into
masterfrom
docs/align-docs-with-repo-state
Aug 26, 2026
Merged

docs: align documentation with actual repo state#35
iap merged 6 commits into
masterfrom
docs/align-docs-with-repo-state

Conversation

@iap

@iap iap commented Aug 26, 2026

Copy link
Copy Markdown
Collaborator

Summary

Four commits bringing the docs in line with what the repository actually contains, after index.html was deleted via the web UI.

  • docs(agents): drop the index.html row and the "starter GitHub Pages page" claim from AGENTS.md; remove the Tips section, whose single item ("Don't change the core apps unless you find a real bug") referenced apps this template does not contain and restated the existing "Keep changes minimal" guideline.
  • chore(coc): remove CODE_OF_CONDUCT.md and its inventory references. The Customization Checklist pointed at a contact method inside it, so it now names SECURITY.md.
  • docs(agents): keep one file inventory, in README.md. Both files carried a table and they had already drifted — README omitted itself, AGENTS.md omitted README.md and CLAUDE.md, and deleting one file meant editing the same row twice. The ci.yml note about Node steps skipping was carried over from the dropped table, and CLAUDE.md gained its own row.
  • docs(contributing): document the commit convention as type(scope): summary, reusing the types already listed for branch prefixes. Records why branch names avoid parentheses: git accepts them, but bash and zsh parse ( as syntax, so every command touching such a branch needs quoting.

Grouped rather than split because the commits touch overlapping lines in AGENTS.md and README.md; as separate PRs a reviewer reads the same regions three times.

Note: this repository is named .github, so removing CODE_OF_CONDUCT.md also removes the account-wide default Code of Conduct for repos that do not ship their own. Reversible from history if unwanted.

Test plan

  • CI passes
  • CodeQL passes
  • Confirm the README.md table lists every tracked file except itself

Greptile Summary

The README now accurately identifies the npm steps that are skipped without a package manifest and reflects the tracked repository files. The contribution guidance documents the repository’s branch and commit conventions.

Confidence Score: 5/5

No blocking failure remains.

The workflow behavior and README inventory were checked for repositories with and without a package manifest; the documented behavior matches the workflow.

T-Rex T-Rex Logs

What T-Rex did

  • Ran a focused validator comparing the revision before the README correction and the current revision to assess the workflow behavior when package.json is absent.
  • Observed that with no package.json, the workflow keeps the Node setup step enabled while conditionally skipping npm ci and npm test, and that the README names those two commands specifically.
  • Verified that the current README's wording aligns with the file inventory, excluding README.md and matching the tracked files after the correction.
  • Documented the pre-change observation that with package.json absent, the README used a broad phrase like “Node steps skip.”
  • Confirmed after the change that setup-node remains unconditional and README names only npm ci and npm test, with the tracked-file inventory passing.

View all artifacts

T-Rex Ran code and verified through T-Rex

Reviews (2): Last reviewed commit: "Merge branch 'master' into docs/align-do..." | Re-trigger Greptile

iap added 4 commits August 27, 2026 00:48
index.html was deleted from the repo, so the Repository Structure row
and the GitHub Pages mention in Project Overview no longer applied.

The Tips section held a single item, "Don't change the core apps unless
you find a real bug", which referenced apps this template does not
contain and duplicated the existing "Keep changes minimal" guideline.
Drop the Contributor Covenant file and the references to it in the
README and AGENTS.md inventory tables.

The Customization Checklist item pointed at a contact method in
CODE_OF_CONDUCT.md, so it now names SECURITY.md instead.

Note: this repo is named .github, so its root community-health files
serve as account-wide defaults for repos that do not ship their own.
README and AGENTS.md each carried a table of the repo's files. They had
already drifted apart: README omitted itself, AGENTS.md omitted both
README.md and CLAUDE.md, and removing CODE_OF_CONDUCT.md meant editing
the same row in two places.

Drop the AGENTS.md table and note in Project Overview that README holds
the inventory. Carry over the ci.yml detail about Node steps skipping,
which only AGENTS.md recorded, and give CLAUDE.md its own row.
Add a Commit Messages section specifying type(scope): summary, reusing
the types already listed for branch prefixes.

Note that branch names should avoid parentheses: git accepts them, but
bash and zsh parse ( as syntax, so every command touching such a branch
needs quoting.

AGENTS.md and the Pull Requests steps said only "descriptive message";
both now point at the new section instead of restating it.
Comment thread README.md Outdated
iap added 2 commits August 27, 2026 01:52
The inventory said Node steps skip when package.json is absent, which
is broader than the workflow does. actions/setup-node has no condition
and runs regardless; only the npm ci and npm test steps carry the
hashFiles guard.
@iap
iap merged commit 175a380 into master Aug 26, 2026
5 checks passed
@iap
iap deleted the docs/align-docs-with-repo-state branch August 26, 2026 19:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant