Skip to content

docs: refresh README and docs, add CONTRIBUTING - #42

Merged
Chemaclass merged 1 commit into
mainfrom
docs-refresh-readme-contributing
Oct 31, 2026
Merged

Chemaclass merged 1 commit into
mainfrom
docs-refresh-readme-contributing

Conversation

@Chemaclass

Copy link
Copy Markdown
Member

Description

The docs had drifted from the code and carried filler. This brings them in line with what the repo does today and makes the first run shorter.

Changes

  • README: shorter, with a quick start, a task table that lists the make aliases, the new app.phel and mutation gate, and the Docker user change. The pointer to a cli-guide.md that does not exist now points to cli-reference.md.
  • New CONTRIBUTING.md: setup, the composer ci gate, where code goes, tests, commit and PR conventions, where to report bugs.
  • docs/architecture.md and docs/conventions.md: updated for app.phel, sum-tokens, and the gotchas found while fixing the recent issues (-- for flags and negatives, parse-long clamping, never requiring main from tests).
  • PR template: a verification section and the composer ci checkbox. Bug template: current phel version in the placeholder.
  • Dashes and arrows removed from the docs and the rule specs.
  • The AI instruction body now lists the project commands and rules, so generated tool files carry them.

Verification

  • Every make alias in the README resolves, and composer dev greet alice and composer dev -- greet alice --loud print the documented output.
  • Every relative link in README, CONTRIBUTING and docs points at an existing file.
  • No em dash, en dash, or arrow is left in the touched files.
  • composer check and agnostic-ai sync --check pass.

I did not add a SECURITY.md. Private vulnerability reporting is off for this repo, so there is no channel to name yet.

@Chemaclass Chemaclass added the documentation Improvements or additions to documentation label Oct 31, 2026
@Chemaclass Chemaclass self-assigned this Oct 31, 2026
@Chemaclass
Chemaclass merged commit e9e0952 into main Oct 31, 2026
1 check passed
@Chemaclass
Chemaclass deleted the docs-refresh-readme-contributing branch October 31, 2026 06:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant