Doctrine of the Second Sun

Doctrine of the Second Sun is a portable collection of literary, visual, coding, technical-writing, and software-stewardship guidance. It defines one fictional scripture with four canonical books while keeping repository-specific placement and enforcement rules in the projects that consume it.

The canonical Markdown is also available as rendered documentation.

Documents

• DOCTRINE-STYLE-GUIDE.md: literary worldview, books, movements, cadence, imagery, and examples.
• DOCTRINE-CODING-GUIDE.md: safe insertion and review of literary marginalia in source code.
• DOCTRINE-IMAGE-GUIDE.md: visual interpretation of completed logia.
• DOCTRINE-GENERATION-GUIDE.md: tool-neutral writer, reviewer, and insertion workflow.
• DOCTRINE-GOLD-EXEMPLARS.md: exceptional reference logia establishing the quality ceiling for generation and review.
• INTEGRATION-GUIDE.md: adopting the portable guides in a consuming repository for humans and coding agents.
• RUINENWERT.md: designing software so its useful knowledge survives active maintenance.
• MEASURE-OF-WORDS.md: concise, clear, and exact writing for technical artifacts.
• CODE_OF_SOVEREIGNTY.md: repository governance and the sovereignty of forks.

Ruinenwert and the Code of Sovereignty are institutional documents. The Measure of Words is technical-writing guidance. None is a book or teaching within the fictional canon.

Composer

Install the documents as a development dependency:

composer require --dev jbboehr/doctrine-of-the-second-sun:dev-master

The package root is then available at:

vendor/jbboehr/doctrine-of-the-second-sun/

Consuming projects should keep their own AGENTS.md or equivalent policy for source scope, tag syntax, citation allocation, asset locations, and verification commands. See the integration guide for the full adoption workflow and a local-policy template.

Nix

Add the repository as a flake input:

inputs.doctrine-of-the-second-sun.url = "github:jbboehr/doctrine-of-the-second-sun";

The default package installs the documents beneath:

share/doctrine-of-the-second-sun/

A consuming development shell can expose that location explicitly:

DOCTRINE_OF_SECOND_SUN_DIR =
  "${inputs.doctrine-of-the-second-sun.packages.${system}.default}/share/doctrine-of-the-second-sun";

Prefer one installation mechanism per consuming repository so Composer and Nix locks cannot silently select different revisions.

Codex Integration

Codex-specific writer and reviewer adapters live under integrations/codex/. They are optional workflow aids rather than part of the tool-neutral doctrine.

PHPStan Integration

The optional integrations/phpstan/ adapter lets consuming PHP repositories enforce their locally selected @logion declaration coverage, citation form, allowed books, and repository-wide uniqueness. It does not choose source roots or command entry points for the consumer and remains disabled unless local configuration or the DOCTRINE_LOGION environment variable enables it.

Browser Integration

The optional browser integrations are framework-independent and inert until mounted:

• Heliogenesis renders the Dawning of the Second Sun;
• The Document Looks Back lets occasional marked letterforms notice the reader.

Neither integration alters a consuming documentation theme merely by being installed.

License

Unless otherwise indicated, the documentation, integrations, packaging files, and artwork in this repository are licensed under the Creative Commons Attribution-ShareAlike 4.0 International License.

The PHPStan adapter implementation, configuration, and tests are licensed under the GNU Affero General Public License version 3 with the Romic Exception. The PHPStan integration’s README.md remains documentation under CC BY-SA 4.0.

When attribution is required, a reasonable form is:

Doctrine of the Second Sun, John Boehr and contributors, https://github.com/jbboehr/doctrine-of-the-second-sun

The package-level SPDX expression is CC-BY-SA-4.0 AND AGPL-3.0-only WITH romic-exception. Adaptations of CC-licensed material must identify their changes and be distributed under the same or a compatible license as required by CC BY-SA 4.0.