Vite + React + TypeScript. The terminal's file system is the real content/home/ folder: add a file there and it appears in ls, cat, grep, find, and tree.

• A file named _about holds the one-line description of the folder it sits in.
• Any other file starting with _ shows up as a hidden dotfile (_secrets becomes .secrets, visible with ls -a).
• Commands live in src/shell/commands.tsx; help and man are generated from that list.

npm install
npm run dev      # local server with live reload
npm test         # shell, file system, and completion tests
npm run build    # type-check and build into dist/
python3 -m venv .venv          # for the Python scripts below, once; a distribution's own Python refuses pip installs
. .venv/bin/activate           # in each new shell
pip install --require-hashes -r requirements.txt   # the same pinned versions the workflow uses

Pushing to main builds and deploys the site through .github/workflows/deploy.yml. In the repository settings, Pages → Source must be set to GitHub Actions.

Languages and tools update themselves. Several times a day (or on demand from the Actions tab → Run workflow), the same workflow runs languages_update_script.py. It reads every repository I own (the public ones, and the private ones too once the STACK_TOKEN secret described below is set, as it is here) — GitHub's language statistics, plus dependency files such as requirements.txt, pyproject.toml and package.json — and rewrites:

• the icon row, tools table, language list and pie chart in this README (between the stack and languages comment markers), and
• src/data/stack.json, which the site's skills and stack commands read.

The On GitHub card is the contribution calendar from my profile page, in this site's colours: activity_card_script.py asks GitHub for the past year and uses the same days, the same counts and GitHub's own shade for each day. It is drawn on every run of the workflow, each push included, and published with the site instead of being committed, so the README always shows the newest one. GitHub caches images for a few minutes, so a fresh contribution can take a little while to appear.

The mood command keeps up with MoodForecast AI. Nothing about that service is written into the terminal by hand more than once:

• Each visit, mood first asks the live service what it offers (its OpenAPI description). Every GET /api/<name>/{location} endpoint is usable at once as mood <name> <place>, every other GET /api/<name> as mood <name>, and any field a response gains is shown, even before the terminal has a tailored view for it. mood api lists what it found.
• What the service says is passed on as it says it: its own error explanations, its questions about other places, its place suggestions when a name is mistyped, and its current list of activities (used for suggestions and Tab completion the same day one is added).
• The scheduled run also executes mood_sync_script.py, which reads the endpoints plus the place lists and activities in the moodforecast_ai repository and writes src/data/mood.json. The terminal uses it for suggestions ("where next?"), Tab completion, and as a fallback when the service does not answer. The same run rewrites the endpoint list visitors can read in the terminal (cat ~/projects/moodforecast-ai/API.md).

Project write-ups keep up with the projects. The same scheduled run executes projects_sync_script.py, which reads the history of every project listed at the top of that script and rewrites:

• the Lately table under Featured work (between the projects comment markers), and each project's source link, which turns into "source is private" on its own if a repository is made private,
• src/data/projects.json, which the terminal's updates and projects commands read, and
• a CHANGELOG.md in each project's folder under content/home/projects/, readable in the terminal with cat.

A private repository's commit messages stay out of all three unless its entry in the script says "share": True; otherwise only its dates and commit count are shown.

Dates and commit lists look after themselves; the paragraphs I wrote about a project do not. So the script also records the commit each write-up was last revised at (projects_reviewed.json) and reports what has changed since. The scheduled run posts that as a notice on the workflow, and on my own machine the same check runs against the local clones, where it also sees work that is not pushed yet:

python3 projects_sync_script.py --check              # ask GitHub (GITHUB_TOKEN needed for private projects)
python3 projects_sync_script.py --check --local ..   # ask the clones next to this one
python3 projects_sync_script.py --mark-reviewed      # after revising the write-ups

To add a project, add a line to PROJECTS in the script and a folder for it under content/home/projects/.

To try MoodForecast AI changes that are not merged or deployed yet, run its backend locally and point both halves at it:

python3 mood_sync_script.py --source ../moodforecast_ai --api http://localhost:8000   # places, activities, endpoints
echo 'VITE_MOOD_API=http://localhost:8000' > .env.local                               # the site's live calls
npm run dev

(git checkout src/data/mood.json content/home/projects/moodforecast-ai/API.md puts the generated files back afterwards.)

The scheduled run commits its changes to main, so git pull before starting new work.

Including private repositories. By default only public repositories are scanned. To count private ones too, create a fine-grained personal access token (GitHub → Settings → Developer settings → Fine-grained tokens) with All repositories access and read-only Contents and Metadata permissions, then save it in this repository under Settings → Secrets and variables → Actions as a secret named STACK_TOKEN. Only totals are published — language sizes and tool names — never private repository names, which are also kept out of the workflow logs.

Only tools named in KNOWN_PACKAGES / KNOWN_FILES at the top of the script are reported; add a line there to teach it a new one. To run it by hand:

python3 languages_update_script.py --dry-run   # preview
python3 languages_update_script.py             # rewrite README and stack.json