docs: Add index page with repository philosophy and structure - #88
Draft
alycda wants to merge 1 commit into
Draft
Conversation
Adapts the Ataraxy Labs index.md pattern (frontmatter tagline, one-line positioning, thesis with three axioms, four live things, colophon, contact) — the same skeleton used for the personal 'Alyssa Evans — Index' page — down one more level, from company to person to repository. The lineage of the opening line drives the adaptation: - 'Software, written for the things that read it' (Ataraxy Labs) - 'Code, written for the people who inherit it' (personal index) - 'Configuration, written for the machines that rebuild it' (this repo) Axioms map to what the repo actually practices: - i 'The commit is the unit' — history-as-artifact, jj workflow - ii 'Declared beats installed' — shared core-packages list, flakes - iii 'The messy middle is the content' — inherited verbatim from the personal index; docs/solutions/ is the proof Links use absolute GitHub URLs for root files so the page survives being published from docs/ as a site root (where ../README.md would break), and the Jekyll-compatible frontmatter means GitHub Pages 'deploy from /docs' renders it as-is.
Contributor
⊕ Entity-level changesdocs/index.md
Summary: 10 added across 1 file functions and classes, not lines · sem |
alycda
commented
Aug 5, 2026
|
|
||
| ## Colophon | ||
|
|
||
| This was supposed to be a weekend of configuration. It became a curriculum. The bee shouldn't fly, and does. |
Owner
Author
There was a problem hiding this comment.
Suggested change
| This was supposed to be a weekend of configuration. It became a curriculum. The bee shouldn't fly, and does. | |
| This was supposed to be a weekend of configuration. It became a curriculum. The bee shouldn't fly, and yet, it _does_. |
alycda
commented
Aug 5, 2026
|
|
||
| ## Reading order | ||
|
|
||
| For humans and agents alike: [README](https://github.com/alycda/dotfiles/blob/main/README.md) for the map, [CLAUDE.md](https://github.com/alycda/dotfiles/blob/main/CLAUDE.md) for the conventions, [CONCEPTS.md](https://github.com/alycda/dotfiles/blob/main/CONCEPTS.md) for the vocabulary, [docs/solutions/](https://github.com/alycda/dotfiles/tree/main/docs/solutions) for the scars. |
Owner
Author
There was a problem hiding this comment.
Suggested change
| For humans and agents alike: [README](https://github.com/alycda/dotfiles/blob/main/README.md) for the map, [CLAUDE.md](https://github.com/alycda/dotfiles/blob/main/CLAUDE.md) for the conventions, [CONCEPTS.md](https://github.com/alycda/dotfiles/blob/main/CONCEPTS.md) for the vocabulary, [docs/solutions/](https://github.com/alycda/dotfiles/tree/main/docs/solutions) for the scars. | |
| For humans and agents alike: [README](../README.md) for the map, [CLAUDE.md](../CLAUDE.md) for the conventions, [CONCEPTS.md](../CONCEPTS.md) for the vocabulary, [docs/solutions/](.//solutions) for the scars. |
alycda
commented
Aug 5, 2026
| @@ -0,0 +1,49 @@ | |||
| --- | |||
| title: "dotfiles — Index" | |||
| tagline: "The Messy Middle, Reproducible" | |||
Owner
Author
There was a problem hiding this comment.
the journey is the destination
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add a comprehensive index page (
docs/index.md) that introduces the repository's philosophy, structure, and reading order. This serves as the entry point for both humans and agents exploring the dotfiles project.Key Changes
docs/index.mdwith Jekyll front matter (title, tagline)Implementation Details
The page emphasizes that this repository documents a learning journey with Nix, not just a final configuration. It positions the commit history and documented solutions as first-class artifacts, aligning with the repository's philosophy of making the "messy middle" valuable through documentation.
Links throughout point to key files and directories in the repository, making it a navigational hub for exploring the project.
https://claude.ai/code/session_01TZuXctAze1wC3nEeWCjSig