Skip to content

docs: domain examples, user guide, Pages site and repo tidy - #2

Merged
bsommers merged 1 commit into
mainfrom
docs/overhaul
Nov 8, 2026
Merged

bsommers merged 1 commit into
mainfrom
docs/overhaul

Conversation

@bsommers

@bsommers bsommers commented Nov 8, 2026

Copy link
Copy Markdown
Owner

Summary

  • 16 new domain examples, each with diagrams, an .expect file and a deliberately contradictory _conflict.logic fixture:
    • industrial and IoT: ICS, IIoT, smart-home IoT, semiconductor fab
    • security: SOC
    • software and engineering: software delivery, aerospace, systems engineering
    • science and health: science lab, research, clinical medicine
    • business: customer service, customer success, food service, logistics, agriculture
  • test/DomainExamplesSpec.hs checks that each example's expected names exist, that the example is consistent (SAT), and that its conflict fixture is UNSAT. A guard test also fails if any examples/domain_*.logic has no fixtures.
  • docs/user-guide/ is a 14-page user guide, checked against real CLI output.
  • docs/:
    • refreshed architecture, purpose and using pages
    • new standard-library.md, so the cybersecurity-only list is gone from the README
    • domain gallery in docs/domains/
    • internal notes moved to docs/dev/
  • site/ and pages.yml add a GitHub Pages site with a neon-blue grid theme. Pages needs Settings → Pages → Source: GitHub Actions.
  • README is cut to 84 lines. .security-reports/ and a stale diagram are removed.

Code under src/ is unchanged. setup.sh now finds its logo at the new path.

Known limitations found while documenting (not fixed here)

These are listed in docs/user-guide/troubleshooting.md:

  • OpenAPI output is invalid YAML for a subclass with its own properties.
  • Python and Java output repeat bounds when a subclass restates an inherited bound.
  • REPL :explain reports no contradiction right after an UNSAT.
  • The native and Vampire provers miss numeric-bound contradictions.

Testing

  • stack test --ghc-options="-Wall -Werror": 745 examples, 0 failures.
  • Every relative link in the README, docs/ and site/ resolves.

🤖 Generated with Claude Code

- 16 new domain examples (ICS, IIoT, IoT, SOC, semiconductor fab, software
  delivery, aerospace, systems engineering, science lab, research, clinical
  medicine, customer service and success, food service, logistics,
  agriculture), each with diagrams, an .expect file and a conflict fixture
- test/DomainExamplesSpec.hs: expected names exist, examples are SAT,
  conflict fixtures are UNSAT, and every domain_* example has fixtures
- docs/user-guide/: 14-page user guide checked against the CLI
- docs/: refreshed architecture, purpose and using pages, a standard-library
  page and a domain gallery; dev notes moved to docs/dev/
- site/ and pages.yml: GitHub Pages site
- README cut to 84 lines; .security-reports/ and a stale diagram removed

Gate: stack test -Wall -Werror, 745 examples, 0 failures.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@bsommers
bsommers merged commit 525478c into main Nov 8, 2026
0 of 2 checks passed
@bsommers
bsommers deleted the docs/overhaul branch November 13, 2026 03:31
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