wherefore-build 0.5.1__tar.gz

wherefore_build-0.5.1/CHANGELOG.md

@@ -0,0 +1,282 @@
+# Changelog
+
+Every release of the engine, newest first. A client pins one commit (its
+`requirements-engine.txt`), and moving that pin is a pull request its own full
+suite judges, so a release reaches no client by itself.
+
+The version is stated in `pyproject.toml`, in `wherefore.__version__` and here,
+and `tests/test_version.py` holds the three together until they are one fact.
+
+## 0.5.1 (2026-11-03)
+
+**What a pre-publication review found.** The first release meant for PyPI.
+Nothing a corpus declares changes; what changes is how the engine behaves when
+what it reads is not what it expected.
+
+- `wherefore check upstream`:
+  - a server that closes before the body it promised now "did not answer",
+    instead of a traceback - and is never read as a shorter body;
+  - `true`, `false` and `null` read from a source and recorded in the corpus are
+    compared as the same JSON, so equal values no longer report MOVED;
+  - a `json` pointer must be `""` or start with `/` (RFC 6901), and anything
+    else is refused in words;
+  - it reads at most 10 MB of an answer, and refuses one past that in words;
+  - a MOVED line prints at most 80 characters of each value;
+  - a recorded-values file that is not JSON is refused naming it.
+- A section included from its own file (`"inventory": "checks/inventory.json"`)
+  that is not JSON is refused naming the file, instead of a traceback.
+- `wherefore scan` on a live address:
+  - `--max-pages` caps every address fetched, not only the HTML pages, so a page
+    linking to hundreds of downloads costs no more than the limit;
+  - an answer that is not HTML is not read past its headers;
+  - a redirect to another host is refused, and reported as not read.
+- The package: `pip install wherefore-build` (or `uv tool install` / `pipx
+  install`) in the README; the licence as an SPDX expression; the project's
+  addresses and author; and an sdist that carries its tests' helpers, fixture
+  and changelog, so its tests run.
+- The README opens with what Wherefore is for - your company, compiled - and
+  the hardware company it was built alongside, and the install section says
+  what it needs: Python 3.10 or later, and nothing else.
+- Contributions from outside are welcome: `CONTRIBUTING.md` says how (an issue
+  first for anything bigger than a fix; Apache-2.0, section 5; each commit
+  signed off under the Developer Certificate of Origin), and
+  `CODE_OF_CONDUCT.md` adopts the Contributor Covenant 2.1. CI runs on every
+  pull request, a fork's included, and on pushes to `main`; a new `sign-off`
+  job checks each commit of a fork's pull request is signed off by its author.
+
+## 0.5.0 (2026-11-03)
+
+**Every surface, held to the source.** The skill's `start.md` gains a step for
+after the first fact compiles: ask where else the product is described - the
+site, the docs, the app's strings, a changelog, often each in its own
+repository - which repository decides each fact, and which may read from
+which. Then set every other surface up the same way: it pins the source, reads
+what the source ships as data instead of typing its own list, and fails its
+build on a feature it does not say, with a deliberate omission written down
+like any exemption. `wherefore init` ends by pointing there.
+
+**Derived from elsewhere: `wherefore check upstream`.** A captured group can
+say where it was taken from when that is outside the repository - another
+company's published file, counts taken from another product's public site - in
+an `upstream`: the address, what to read there (a JSON pointer, a meta tag, or
+a pattern, optionally base64-decoded), and what must still match - the group's
+one file byte for byte, or a version the corpus records once, in a tracked
+JSON file. `wherefore check upstream` reads each one now, and fails:
+
+- **MOVED** when the source says something else: take the copy again, and
+  record the new version in the same change - never the number alone;
+- **no longer says** when the source answered without what `read` looks for:
+  it changed shape, which is a change too;
+- **did not answer**, unless the upstream gives the reason a source being down
+  should not stop this corpus.
+
+It is the one command that goes to the network, so it is never part of the
+gate, the build or the pre-push hook: the gate stays offline, and the same
+tree always gives the same answer. Run it where the corpus is compiled for a
+deploy. The skill says what to do when it fails.
+
+**One skill, one feature.** "The skill, for Claude Code" and "The skill, for
+Codex" were two features in 0.4.0, for one skill written in two places. They
+are one now - "The skill, for Claude Code and Codex", since 0.2.0 - so a page
+that lists what the engine does says it once. A client with words for `codex`
+is told the release no longer ships it, and drops them.
+
+**Every release, said once as data: `releases.json`.** Each release's version,
+date, title, one sentence, and a picture of it working - the command it is
+best shown by and what it printed. It ships in the package, so the company's
+changelog page is built from the release it pins: it lists every release, and
+cannot list one that was never cut. `tests/test_releases.py` holds it to this
+file's headings, every feature to a release that was cut, and the newest
+release to the version `pyproject.toml` states, so a version cannot move
+without its entry. The newest release's picture is run again on every change,
+so it cannot drift from what the engine prints. The pictures of earlier
+releases were made by running each tagged release.
+
+## 0.4.0 (2026-11-03)
+
+**The skill reaches Codex.** Codex reads a repository's skills from
+`.agents/skills/<name>/SKILL.md` - the open Agent Skills format, the same one
+Claude Code reads from `.claude/skills/` - so the skill generator now writes
+the one skill the release ships to both places:
+
+- `wherefore init` writes `.claude/skills/wherefore/` and
+  `.agents/skills/wherefore/`, and says which agent reads which;
+- the `wherefore.skill` generator writes both on every build, and the gate
+  holds each copy to the release: an edit by hand to either is named;
+- `start.md` says where both live.
+
+**What the engine does, as data: `features.json`.** Each feature, the release
+it arrived in, and its commands - whose words stay in `commands.json` - or its
+own words if it has none. It ships in the package, so a client that describes
+the product (the company's site) reads it from the release it pins and must
+say something about every feature, or its build stops: a release that adds a
+feature fails every page that does not yet tell people about it. Every command
+belongs to exactly one feature, and a test fails a command that belongs to
+none. The README's "What it does" is generated from it.
+
+A corpus that already declares the generator writes the Codex copy at its next
+build after moving its pin. That copy is generated, so a rule that claims
+`*.md` as authored needs `.agents/skills/wherefore/*` excepted, as it already
+excepts the Claude Code copy.
+
+## 0.3.0 (2026-11-03)
+
+**`wherefore scan`, the first win with no setup.** Point it at what a company
+publishes - a built site, a docs folder, exported notes, or a live site's
+address - and it reports every value stated more than one way:
+
+    "start your {} day free trial"  - said 4 times, 2 ways
+       14   3x   site/index.html:2, docs/start.md:3, site/pricing.html:1
+       30   1x   help/billing.md:1
+
+- It needs no `wherefore.json`: the scan comes before there is a corpus.
+- A statement is a value with real words on both sides, keyed by the words
+  around it; a version is keyed by the name in front of it.
+- What it reports is a stale copy - the same statement in more than one file,
+  saying at most three things, the commonest at least as often as the rest.
+  It leaves alone identifiers (P-005, V83), dates, history ("since 2.1"),
+  tables of different things, numbered lists, code, and files that are history
+  by name unless `--all` asks for them. It would rather miss a disagreement
+  than invent one.
+- Pages are read the way a person reads them: sentences across inline tags,
+  a picture's alt text, a page's description; script, style and code are not.
+- A live address is read page by page on its own host, up to `--max-pages`
+  (50). `--json` lists every statement and every place.
+- Exit status 1 when copies disagree, so it can stand in CI before a corpus
+  does.
+- The skill's `start.md` begins the count with it.
+
+Run on `chaotic-pendulums-co`'s docs, pack and brand - 152 files - its one
+report was real: two brand documents give the swing's damping as viscous x60
+and x8.
+
+## 0.2.1 (2026-10-30)
+
+What a fresh review found, fixed, and ready to be published. Every fault
+below was reproduced on the fixture company first, and each now has a test
+that plants it (`tests/test_false_passes.py`, `tests/test_hook.py`).
+
+**The gate no longer passes when it should fail:**
+- a generator that succeeds on the first pass and throws on the second is a
+  failure, not "the corpus settles";
+- a tracked file missing from the working tree is said, not compared with
+  nothing - the pre-push hook passed a stale tree that way - and the gate
+  leaves it missing, as it found it;
+- `--restamp` takes exactly one group: re-stamping every group at once would
+  certify captures nobody re-made;
+- a captured group must say what it was made from (`shot_from`,
+  `spec_values`) or why there is nothing (`no_stamp`, with the reason), and
+  must name its `files`. A group with neither stamped the hash of nothing and
+  passed for ever.
+
+**`check retired` and `check claims` read what they missed:**
+- a page whose name is not plain ASCII (`précis.html`) was never read: git
+  quoted the name and it matched no file;
+- a retired number is searched for written out in full - a million was
+  searched for as `1e+06` - with a thousands comma and trailing zeros allowed,
+  so 12.5 finds "$12.50" and 1000000 finds "1,000,000".
+
+**The pre-push hook:**
+- when git cannot say what a push changes - the first push of a new
+  repository, or a remote tip this clone has not fetched - it rolls the corpus
+  rather than assume nothing moved;
+- nothing is skipped unless `hook.skip` says so. Prose was skipped by default,
+  which excused a Markdown template a generator reads;
+- it runs with the interpreter the engine is installed in, not whatever
+  `python3` is on PATH, which blocked every push from a virtual environment.
+
+**Commands:**
+- it runs on Python 3.10 and 3.11, as it says: a backslash inside an
+  f-string made `generators.py` a syntax error before 3.12, and CI now tests
+  3.10 to 3.13;
+- `wherefore init` and then `wherefore gate` does what init says - names every
+  file nobody has accounted for - instead of refusing a corpus with no source
+  yet;
+- `wherefore prove` with a `proofs` glob that matches nothing fails: "0/0
+  proofs held" passed;
+- a flag a command does not take is refused, not ignored (`gate --kep` ran
+  the whole gate), and `--help` prints the usage and runs nothing;
+- a generator `cwd` that does not exist, a directory that is not a git
+  repository, an inventory with no `captured` section, and a capture reading
+  `spec_values` from an untracked source each say so, instead of a traceback;
+- `wherefore list` says that what it wrote is left in the working tree.
+
+Ready to be published, not published. The owner decided on 2026-10-30 that the
+engine is open source.
+
+- **Apache-2.0** (`LICENSE`), and the distribution is renamed
+  **`wherefore-build`**: `wherefore` on PyPI is another project's. The import
+  name and the command are still `wherefore`. A pin that names a commit after
+  this one must say `wherefore-build @ git+...`.
+- **`release.yml` can publish to PyPI** by trusted publishing, with no token
+  stored - but only while the repository variable `PUBLISH_TO_PYPI` is `true`,
+  which the owner sets when it is time.
+- **`PUBLISHING.md`:** what the public repository leaves out (the pendulum's
+  patch series and the design records about its internals), and the steps.
+  **`CONTRIBUTING.md`** and **`SECURITY.md`**.
+
+## 0.2.0 (2026-10-30)
+
+The skill ships with the engine, and starts a corpus as well as working in one.
+
+- **A second half of the skill, `start.md`:** the first session in a
+  repository with no corpus yet, for a coding agent. It interviews the owner
+  (what the company says in more than one place, where, and which systems
+  already own a fact), counts every copy before changing anything, and takes
+  one fact end to end - source, generator, reach, the hook and CI - before a
+  second asset is touched. `SKILL.md` sends an agent there when there is
+  nothing to work in yet.
+- **The skill is in the package** (`src/wherefore/skills/wherefore/`), so each
+  release carries the skill that matches its commands, and
+  `corpus/commands_named.py` reads both files.
+- **A corpus's copy is generated, not kept.** `wherefore init` now declares one
+  generator, `python -m wherefore.skill`, which writes the release's skill into
+  `.claude/skills/wherefore/` on every build. The gate holds that copy to the
+  pinned release: move the pin and the skill moves with it, or the gate names
+  the file that did not.
+- **A generator's `script` may be `-m MODULE`,** run as `python -m` runs it, so
+  a corpus can declare a module of an installed package without a copy of it.
+
+## 0.1.1 (2026-10-28)
+
+Wherefore on Wherefore: this repository becomes a client of its own engine.
+
+- **The commands are said once,** in `src/wherefore/commands.json`:
+  - `wherefore --help` prints them from there;
+  - the README's list is generated from them (`corpus/readme.py`);
+  - `tests/test_commands.py` holds the CLI's own dispatch to them.
+
+  The three hand-typed lists had already drifted: the README's was missing
+  both `hook` commands.
+- **So are the principles,** in `src/wherefore/principles.json`. The README
+  states them from there, and so can a client: both files ship in the
+  package, so the company's site reads them from the release it pins.
+  `tests/test_package_data.py` fails a data file the wheel would leave out.
+- **This repository's own corpus is gated** (`wherefore.json`), by the
+  previous release (`requirements-engine.txt`), never by the code being
+  edited, the way a compiler builds itself. `corpus/commands_named.py` fails
+  any user-facing document that tells a person to type a command the CLI does
+  not have.
+- **The version moves whenever the engine does** (`corpus/version_moves.py`,
+  #32), and a release is tagged and published from `CHANGELOG.md` by
+  `.github/workflows/release.yml`, never by hand.
+
+## 0.1.0 (2026-10-28)
+
+The first release: the machinery extracted from chaotic-pendulums-co, moved
+rather than rewritten, with the pendulum as its first client.
+
+- **Moved, byte for byte but for recorded edits** (`tools/moved/`): the
+  generator runner and the roll, the write observer, the coverage gate, the
+  comparators (pictures, numbers, workbook cells, inlined pictures), the proof
+  harness, the retired-facts sweep and the source-reach probe.
+- **New:**
+  - `wherefore.json`, with includes and a required `why` for every
+    exemption;
+  - `entry`, for a client that configures the engine in Python;
+  - the CLI: `init`, `list`, `build`, `gate`, `prove`, `check retired`,
+    `check reach`, `check claims` and `hook install`;
+  - two source adapters (`params`, `leaves`);
+  - the claim rule.
+- **Proved** against a fictional client, `tests/fixture/`. Each proof breaks it
+  one way and requires the right failure, in the right words.

wherefore_build-0.5.1/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

wherefore_build-0.5.1/MANIFEST.in

@@ -0,0 +1,6 @@
+# The sdist carries what its tests need to run: the shared helpers, the
+# fictional company they prove the engine against, and the changelog the
+# version and release tests hold the package to.
+include CHANGELOG.md
+include tests/_util.py
+recursive-include tests/fixture *

wherefore_build-0.5.1/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: wherefore-build
+Version: 0.5.1
+Summary: A company that compiles: every asset generated from one source of truth, every change proven.
+Author-email: Wherefore <hello@wherefore.build>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://wherefore.build
+Project-URL: Repository, https://github.com/wherefore-build/wherefore
+Keywords: build,documentation,single source of truth,ci,agents
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pictures
+Requires-Dist: pillow; extra == "pictures"
+Requires-Dist: numpy; extra == "pictures"
+Provides-Extra: xlsx
+Requires-Dist: openpyxl; extra == "xlsx"
+Dynamic: license-file
+
+<!-- Generated by corpus/readme.py from docs/README.template.md, src/wherefore/commands.json, features.json and principles.json. Edit those, not this. -->
+# Wherefore
+
+**Your company, compiled.**
+
+Code has one source of truth: change it once, and everything built from it
+follows. Everything else a company makes - the website, the docs, the pricing
+page, the app's own words - is a copy of a copy, kept by hand, and it drifts.
+
+Wherefore gives everything else what code has. Say each fact once. Generate
+every asset from it. Anything left stale stops the change before it ships. AI
+writes the rules; the build never improvises.
+
+## A hardware company, compiled from one spec file
+
+Wherefore was built alongside Chaotic Pendulums, a small hardware company
+started to test the idea on something with more surface area than software. If
+one source can hold machined parts, physics, suppliers and a storefront, it can
+hold your app, website and docs. [How it is built](https://wherefore.build/#case).
+
+## What it does
+
+- **Scan** (since 0.3.0): where each stated value appears, and where the copies disagree; needs no setup. `wherefore scan PATH|URL ...`
+- **Start a corpus** (since 0.1.0): write a wherefore.json that declares nothing yet. `wherefore init [DIR]`
+- **The gate** (since 0.1.0): every tracked file classified, every generated one current; puts the tree back unless --keep. `wherefore gate [--keep]`, `wherefore gate --restamp GROUP`
+- **The build** (since 0.1.0): the roll: every generator, twice, compared with what is committed, and the results left in place. `wherefore build`, `wherefore list`
+- **Proofs** (since 0.1.0): run the client's proofs, one at a time, in place. `wherefore prove [SCRIPT ...]`
+- **Retired facts** (since 0.1.0): nothing a person reads still claims a retired value or phrase. `wherefore check retired`
+- **Reach** (since 0.1.0): every fact, moved one at a time, reaches what it should. `wherefore check reach`
+- **Claims** (since 0.1.0): every claim says only what its rule allows. `wherefore check claims`
+- **Derived from elsewhere** (since 0.5.0): every copy taken from elsewhere still matches where it was taken from, read there now. `wherefore check upstream`
+- **The pre-push hook** (since 0.1.0): a pre-push hook: no push leaves the corpus stale. `wherefore hook install`, `wherefore hook pre-push`
+- **The skill, for Claude Code and Codex** (since 0.2.0): teaches your coding agent the rules, and starts a corpus with you: one fact, end to end. One skill, written where each agent reads it, and held to the release
+
+## The principles it enforces
+
+1. **A fact exists in exactly one place.** Everything else is generated from it or checked against it.
+2. **The build is deterministic.** Nothing in the build path calls a model.
+3. **Fail loudly.** A change the build cannot handle stops it; nothing improvises.
+4. **A check is not trusted until it has been shown to fail.**
+5. **Sources versus outputs.** Every tracked file is *generated*, *authored* or *captured*. Generated files are never hand-edited, and a capture is stamped with what it was made from.
+
+## Install
+
+```
+pip install wherefore-build       # Python 3.10+, standard library only
+uv tool install wherefore-build   # or, as a command of its own
+pipx install wherefore-build      # the same, with pipx
+pip install 'wherefore-build[pictures,xlsx]'  # for picture and workbook comparison
+```
+
+It needs Python 3.10 or later and nothing else. Your project can be in any
+language: Wherefore reads and checks files, whatever made them. With no Python
+on the machine, `uv tool install` fetches one. Generators are Python scripts
+today, and one can call anything - a CAD export, a Node build, a shell command.
+
+The distribution is `wherefore-build`, because `wherefore` on PyPI is another
+project's. What you import and what you type are `wherefore`.
+
+## Use
+
+```
+pip install -e .                 # from a checkout of this repository
+pip install -e '.[pictures,xlsx]' # with picture and workbook comparison
+
+wherefore scan PATH|URL ...     # where each stated value appears, and where the copies disagree; needs no setup
+wherefore init [DIR]            # write a wherefore.json that declares nothing yet
+wherefore gate [--keep]         # every tracked file classified, every generated one current; puts the tree back unless --keep
+wherefore gate --restamp GROUP  # record a re-made capture against its sources
+wherefore build                 # the roll: every generator, twice, compared with what is committed, and the results left in place
+wherefore list                  # run every generator once and say what each wrote
+wherefore prove [SCRIPT ...]    # run the client's proofs, one at a time, in place
+wherefore check retired         # nothing a person reads still claims a retired value or phrase
+wherefore check reach           # every fact, moved one at a time, reaches what it should
+wherefore check claims          # every claim says only what its rule allows
+wherefore check upstream        # every copy taken from elsewhere still matches where it was taken from, read there now
+wherefore hook install          # a pre-push hook: no push leaves the corpus stale
+wherefore hook pre-push         # what the installed hook runs before a push; not for typing
+```
+
+**Start with a scan.** `wherefore scan` needs no setup and no `wherefore.json`:
+point it at a built site, a docs folder or a live address, and it reports every
+value the company states more than one way - "start your {} day free trial", 14
+in three places and 30 in one. Each is a fact to say once, in a source, and
+build every copy from; the rest of Wherefore is how.
+
+A client describes its corpus in `wherefore.json`: its sources, its generators
+in order, its inventory of authored and captured files, and every exception to
+byte-identity. Every exemption carries a `why`, and the engine refuses an entry
+that has none. `tests/fixture/` is a complete, fictional example.
+
+A client that configures the engine in Python instead, in the scripts its
+proofs plant faults into, names those scripts in `entry`, and each command runs
+the client's own script exactly as its CI does. The engine refuses a command
+that is handed over and configured in `wherefore.json` as well, because that is
+one fact in two places. Chaotic Pendulums is that kind of client.
+
+## This repository
+
+| path | what |
+|---|---|
+| `src/wherefore/` | the engine |
+| `tests/fixture/` | Fernhollow Kettles, a fictional company the engine proves itself against |
+| `proofs/` | the engine's proofs: each breaks the fixture one way and requires the right failure, in the right words |
+| `tests/` | unit tests, and `test_phase5.py`: the fixture compiled from its sources alone |
+| `tools/moved/` | the exact edits that turned each pendulum original into an engine module; `verify.py` re-runs them |
+| `src/wherefore/skills/wherefore/` | the skill, shipped in the package: how a coding agent works in a corpus (`SKILL.md`) and starts one (`start.md`). A corpus's own copies are generated from the release it pins, by the `wherefore.skill` generator `wherefore init` declares: `.claude/skills/wherefore/` for Claude Code and `.agents/skills/wherefore/` for Codex, the same files in the open Agent Skills format |
+| `CHANGELOG.md` | every release, newest first; a client upgrades only by moving its pin |
+| `src/wherefore/releases.json` | every release again, as data - version, date, a title, a sentence and a picture of it working - for the company's changelog page; `tests/test_releases.py` holds it to `CHANGELOG.md` and runs the newest picture again |
+| `corpus/`, `wherefore.json` | this repository as a client of its own engine: the README's generator, the corpus's checks and their proofs |
+| `docs/README.template.md` | the README's text; the README is generated from it, `src/wherefore/commands.json` and `src/wherefore/principles.json` |
+| `requirements-engine.txt` | the previous release, which judges this repository's own corpus |
+| `LICENSE` | Apache-2.0 |
+| `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md` | how to work on the engine and contribute to it, how everyone taking part behaves, and how to report a vulnerability |
+| `PUBLISHING.md` | how a release reaches PyPI, and what this repository's history leaves out |
+
+```
+python3 -m unittest discover tests
+for p in proofs/*_proof.py; do python3 "$p" || exit 1; done
+```
+
+## Licence
+
+Apache-2.0 (`LICENSE`). The package is published as `wherefore-build`; what you
+import and what you type are `wherefore`.