Split favicon off from the logo — new docs/assets/favicon.svg (purple
gradient lambda), mkdocs favicon key repointed to it; logo unchanged.
Signed-off-by: disqualifier <dev@disqualifier.me>
- Workflow: paste.rethinkstudios.io pastebin section — pb() function
(recommended) + alias alternative in content tabs, usage, expires note,
creation rate-limit warning.
- Deploy: warning admonition distinguishing ${LOGS_DIR} (app logger, to
disk) from container stdout/stderr where startup crashes and uncaught
exceptions land; sys.excepthook snippet to route them into the log file.
Signed-off-by: disqualifier <dev@disqualifier.me>
- 'The whole flow' is now plain prose, not an abstract box.
- Restore the v2 diagram shape (git -> staging via develop-if-gitflow AND
git -> deployment, converging on docker) instead of the linear main-only
one, keeping the simplified 'libs (rethink-public, pip)' wording.
- Spread admonition types for variety across pages: index agent-callout
tip -> example; environments uv.lock note -> info; standards logging
note -> info. (deploy already mixes success/danger/example/warning/tip.)
Verified in-browser: whole-flow reads as text, diagram renders in the v2
shape; mkdocs build --strict clean.
Signed-off-by: disqualifier <dev@disqualifier.me>
- Move the flow diagram up into 'Preparing for Deploy' (was a separate
section at the bottom); drop that trailing section.
- Use more admonition types for visual variety: success (what can run),
abstract (the whole flow), example (container-path), success (same file
both places) — alongside the existing danger/warning/tip.
- Simplify the diagram: libs -> 'libs (rethink-public, pip)', the git edge
-> 'branch', staging -> 'main'; abstract intro reworded to branch+main.
- Trim the Compose tab: drop the rules list that duplicated the inline
comments + danger box; tighten the storage tiers.
Verified in-browser: diagram renders with simplified nodes near the top,
six admonition types present; mkdocs build --strict clean.
Signed-off-by: disqualifier <dev@disqualifier.me>
Collapse the deploy sub-pages back into one deploy.md (tabs, not separate
pages), add a working mermaid flow diagram, and rework the top per feedback.
- Mermaid: enable via superfences fence_div_format (the fence_code_format
<pre><code> wrapper broke mermaid's render — div format fixes it); vendor
mermaid.min.js locally (no CDN dependency for a self-hosted site) + a small
init that renders each block once and survives instant-nav.
- Content tabs Compose / Dockerfile / Secrets hold the three pieces together
on one page (inline comments in the code, no annotation +).
- 'What can run here' tip moved above the flow; section renamed
'Preparing for Deploy' with the 'you don't run deploy commands' point folded
sparsely into the intro (standalone note removed); 'svc never changes'
called out.
- Flow diagram (below the tabs): build group now includes our libraries; git
-> staging shown as develop-if-gitflow (dotted); deployment (no MR-to-main)
-> docker image built + run on the fleet.
- Revert inbound links to deploy.md.
Verified in-browser: diagram renders with all nodes, tabs switch, section
order correct; mkdocs build --strict clean.
Signed-off-by: disqualifier <dev@disqualifier.me>
The Deploy page got long and the code annotations rendered inconsistently
(some as (n) numbers, some as clickable +, and a marker on a fully-commented
line made that line vanish). Fix both:
- Deploy is now a HUB (docs/deploy/index.md): the intro + collision rule +
central-deploy note, then card links to three focused sub-pages. Deploy
stays the single global-nav entry; sub-pages are not_in_nav, reached from
the hub cards.
- deploy/compose.md — compose convention, storage tiers, how deploy fills
it in, subprocess/browser knobs, checklist
- deploy/dockerfile.md — services-account image, COPY, layer caching, uv
- deploy/secrets.md — keeping secrets out of the image
- Replace code annotations with INLINE COMMENTS on the compose/Dockerfile
examples: everything visible at once, no + to click, and the commented
MOUNTS_DIR line no longer disappears.
- Update inbound links (index card, standards, workflow, environments) to
deploy/ and deploy/compose.md; nav Deploy -> deploy/index.md with
not_in_nav for the sub-pages.
Verified in-browser: hub cards link correctly, sub-pages render with visible
inline comments (0 annotation markers), left nav shows only Deploy;
mkdocs build --strict clean (validates not_in_nav + all cross-links).
Signed-off-by: disqualifier <dev@disqualifier.me>
A '# (6)!' annotation marker on a fully-commented YAML line made Material's
annotation JS swallow the whole line into the tooltip — so the commented
'# - ${MOUNTS_DIR...}' line disappeared, leaving an orphan marker with no
visible code (which is why '(6)' seemed missing).
Fix: drop the marker from the commented line, keep it as plain visible YAML
('# optional — see below'), and move its explanation to prose below the
annotation list. Renumber cache/volume markers 7->6, 8->7.
Verified in-browser: commented mounts line now renders visibly; no orphan
marker. build --strict clean.
Signed-off-by: disqualifier <dev@disqualifier.me>
Make the volume mapping explicit: the right-hand mount path is where the
app writes. WORKDIR is /app, so code writing to ./cache lands in /app/cache
(this mount); same for /app/logs and /app/config. Removes ambiguity about
which side of the volume line the code targets.
Verified: mkdocs build --strict clean.
Signed-off-by: disqualifier <dev@disqualifier.me>
Devs never deploy — that's a central ops tool. Remove operator-facing
content and keep only what a dev is responsible for (a conforming compose).
- remove the 'Onboarding a service' section (deploy <host> <workspace>
<git-url> command + deploy-key internals) and the 'How deploy fills it in'
docker-ps collision table + <workspace>/<name> naming internals
- replace with 'Deployment is handled centrally': a note that devs run no
deploy commands, plus the kept dev-facing context that the env is
GENERATED at deploy time so ${LOGS_DIR}/${CONFIG_DIR}/${MOUNTS_DIR}
resolve without them (less ambiguous than just 'it's handled')
- trim operator leftovers: svc-<ws>-<name> unit ref, dangling '(below)',
and the /srv/config/<ws>/<name> path in the secrets note
Compose convention, uid 1337, restart, mounts tier, layer caching, uv,
subprocess knobs all unchanged. Verified in-browser; build --strict clean.
Signed-off-by: disqualifier <dev@disqualifier.me>
The deploy scripts already handle mounts (dir creation + MOUNTS_DIR
injection); only the docs had dropped it. Re-add it as opt-in so scripts
and docs agree:
- compose: a commented '# - ${MOUNTS_DIR:-./mounts}:/app/data' line — the
dir is auto-created and MOUNTS_DIR injected, but the mount line stays
dev-opted (container-side path is app-specific, can't be auto-mounted)
- reframe the storage tip as 'Three tiers of storage': logs+config (ours),
mounts (optional, injected + auto-created, mount line opt-in), named
volumes (yours)
- re-add MOUNTS_DIR to the injected env vars (noted opt-in) and mention it
in the local-fallback tip, paths line, and checklist as optional
Verified in-browser; mkdocs build --strict clean.
Signed-off-by: disqualifier <dev@disqualifier.me>
- deploy.md: new 'Getting your files into the image' subsection — a
multi-tab annotated block (single file / directory / deps-first) showing
COPY <src> <dest> patterns, plus a warning not to COPY secrets.
- clarify volume ownership: 'Logs and config are ours; the rest is yours' —
we inject/manage the logs + config host mounts; devs put everything else
in named volumes Docker owns.
- remove all /srv/mounts: dropped the MOUNTS_DIR volume + env var and every
mounts reference from the compose block, injected-vars, paths line, and
checklist. environments.md + index.md mounts mentions cleaned too.
Verified in-browser: COPY tabs switch, volume tip renders, zero mounts refs
remain; mkdocs build --strict clean.
Signed-off-by: disqualifier <dev@disqualifier.me>
Supersedes the prior 'name everything after the repo' guidance, which caused
container-name collisions at fleet scale. The dev's compose now names nothing
repo-specific; the deploy layer injects identity and host paths.
deploy.md:
- replace the 'One name everywhere' danger callout with 'Your compose names
nothing repo-specific' (no container_name, no hardcoded names/paths)
- rewrite the compose example to the standard: svc service key,
restart: unless-stopped (required — host unit is oneshot), host paths via
${LOGS_DIR}/${CONFIG_DIR}/${MOUNTS_DIR} with :-./ local fallbacks, bare
'cache' volume. Keep user: "1337:1337" + HOME=/tmp (the services account
identity — not repo-specific)
- add 'How deploy fills it in' (injected env vars a dev can rely on + the
resulting docker ps names) and 'Onboarding a service' (deploy <host>
<workspace> <git-url> [name], deploy key handled via Gitea API)
- update paths to <name>, subprocess example to svc, checklist to the new
rules; drop docker CLI from secret rotation (host-side edit, we restart)
standards.md:
- add a 'Service compose' section: short convention + Right/Wrong tabs
(the nova before/after), linking to the Deploy guide for the full detail
Kept the services-account (1337) section and uid-agnostic Dockerfile notes.
Verified in-browser; mkdocs build --strict clean (cross-ref anchor resolves).
Signed-off-by: disqualifier <dev@disqualifier.me>
Add a prominent danger admonition ('One name everywhere — repo = container =
volumes') right under the intro: the repo name is the name; the compose
service key, container_name, and every named volume must all use it. Spell
out the consequence — mismatched names break deploy, monitoring, and log
scraping, which key off the repo name.
Make the compose example teach it: rename yourapp -> myrepo throughout
(service key, container_name: myrepo, myrepo-data volume) with annotations
calling out each spot where the repo name must appear.
Verified in-browser; mkdocs build --strict clean.
Signed-off-by: disqualifier <dev@disqualifier.me>
uv is presented as the recommended faster, standards-compliant drop-in;
pip stays the baseline/fallback. uv command syntax verified against
docs.astral.sh/uv before writing.
environments.md:
- new 'uv (optional, faster)' section: install from pyproject
(uv pip install . / -e . / '.[dev]'), the uv sync managed-venv flow,
and a note that uv.lock is local-only/gitignored (not committed)
- pinning subsection: pin direct deps in pyproject via == or git @ref,
with a warning that this pins direct deps only — transitive deps still
float at build time (documented tradeoff)
- uv equivalents added beside pip in the Local .venv and Docker tabs
deploy.md:
- 'Faster builds with uv' tip: uv-from-ghcr COPY, ENV UV_COMPILE_BYTECODE=1,
uv pip install --system . (reads pyproject, no lock)
- layer-caching shows the uv variant beside the pip one
- checklist notes uv pip install + UV_COMPILE_BYTECODE; fix stray 'configs'
plural -> 'config'
.gitignore: ignore uv.lock (local-only, never committed).
Verified in-browser; mkdocs build --strict clean (anchors resolve).
Signed-off-by: disqualifier <dev@disqualifier.me>
- deploy.md: /srv/configs -> /srv/config (singular is canonical) across the
compose mount, paths table, secrets path, and rotation snippet. Add the
repo+compose row (/srv/docker/<workspace>/<project>, created by the clone,
not pre-provisioned) and a note that all /srv paths are owned by the
services user (1337) — rounding out the canonical layout.
- workflow.md: the first 'per-project git identity' link pointed at a
nonexistent #per-project-git-identity anchor; point it at #handy-shell-setup
(where the gitsetup alias lives), matching the other link to the same spot.
Did not touch pip/requirements, chmod a+rwX + user 1337, HOME=/tmp, init,
layer caching, or the git-install caveat — all intentional standards.
Verified: mkdocs build --strict clean (validates anchors); table renders.
Signed-off-by: disqualifier <dev@disqualifier.me>
Host paths now follow one shape: /srv/<kind>/<workspace>/<project>/ across
configs, logs, and mounts (mounts added as its own row; configs gains the
workspace segment it was missing).
- deploy.md: compose volumes, paths table, secrets path + rotation snippet
all use <workspace>; add a yellow (warning) admonition ABOVE the table
explaining it — individual dev = lowercase username (ricky, xattam),
shared/official project = workspace (bots, web, apis) — so it stands out
from the all-blue palette and reads before the table.
- index.md: placeholder example uses <workspace>.
Verified in-browser; mkdocs build --strict clean.
Signed-off-by: disqualifier <dev@disqualifier.me>
The 'from git' tab now tells the agent to read docs/ straight from the
repo URL instead of git-cloning it into the working project — clone to
/tmp only if it needs a local copy.
Signed-off-by: disqualifier <dev@disqualifier.me>
A tip admonition under the intro telling devs to point their coding agent
at the handbook for awareness of our libs/standards/deploy rules, with
copy-pasteable agent prompts in two tabs: from the live site, or from a
git clone of the repo.
Verified in-browser: tabs switch, prompts + clone command render, copy
buttons present; mkdocs build --strict clean.
Signed-off-by: disqualifier <dev@disqualifier.me>
- index.md: 'building and shipping with Rethink Studios' -> 'building and
shipping on our network' (it's the network, not the company)
- workflow.md + its index card: 'how we actually work day to day' ->
'get hands on with how we dev'
- deploy.md: drop the 'see the light / ready to host whatever you've built'
pitch for a plain 'how a project gets onto rethink-net'; trim the now-
duplicate eligibility tip
Signed-off-by: disqualifier <dev@disqualifier.me>
The handbook is served natively (no Docker) on the Gitea box: a python
venv runs mkdocs build, and the reverse proxy serves the static site/ at
docs.rethinkstudios.io. Pin the build deps so the host venv reproduces the
build exactly:
pip install -r requirements.txt && mkdocs build
Verified the host rebuild flow from scratch: fresh venv + clean
pip install -r requirements.txt + mkdocs build --strict builds all 6 pages
with no errors. Static output uses relative URLs and site_url is the docs
subdomain, so it serves correctly behind the proxy at the subdomain root.
site/ and .venv/ stay gitignored.
Signed-off-by: disqualifier <dev@disqualifier.me>
New docs/environments.md, nav 'Virtual environments' (before Deploy):
- the rule: never touch system Python (danger callout)
- project-based isolation as Local .venv / Makefile-driven / Docker tabs,
each with a runnable snippet; Docker ties back to the deploy standard
- local dev with pyenv: why, official install link, shell init with
annotated lines, everyday use, per-project .python-version
- shell quality-of-life extras (flake8 alias, .local/bin + npm-global PATH),
cross-ref'd to Standards and Workflow
workflow.md pyenv bullet now points at the new page; index.md gains a card.
Verified in-browser: tabs switch (Local/Makefile/Docker), annotations and
admonitions render; mkdocs build --strict clean (cross-ref anchors resolve).
Signed-off-by: disqualifier <dev@disqualifier.me>
deploy.md:
- fix logs path to /srv/logs/<dev>/<project>
- reframe permissions as a deployer-side heads-up (bind-mount ownership is
handled at deploy time; 'if your bot won't start or logs vanish, flag us')
instead of a dev task / heavy footgun
- git in the image only when the container needs it (host always has git)
- NEW: layer caching (requirements before code copy)
- NEW: subprocess/browser workloads — init:true (tini + PID-1 shell-wrapper
gotcha), shm_size 2gb, mem_limit; with code annotations and a warning
- refresh the compose-needs checklist accordingly
standards.md:
- NEW: licensing — no per-file headers; single top-level LICENSE only when a
repo is for outside use
Verified: mkdocs build --strict clean; new deploy sections rendered.
Signed-off-by: disqualifier <dev@disqualifier.me>
- Rename site 'a rethink development' -> 'rethink development' (site_name,
landing H1); copyright -> 'rethink development (handbook)'.
- libraries.md: remove the 'if the live list is empty' admonition now that
Gitea CORS is fixed.
- extra.css: improve Library-column readability — brighter #cfe6ff code
chips on a cyan-tinted bg, more weight, roomier cell padding (0.7/1em),
nowrap lib names, accent-colored links.
Signed-off-by: disqualifier <dev@disqualifier.me>
- libraries.md: render the live lib list as a 3-column table (Library /
What it does / Language), wrapped in .rt-lib-table so it picks up
explicit styling (Material only auto-styles markdown tables, not
innerHTML-injected ones — that's why it rendered bare before).
- extra.css: branded table (navy header, blue borders, hover rows,
code-styled linked names) and a blue Language badge.
Verified in-browser against real Gitea API data (14 repos fetched,
handbook denylisted -> 13 libs): table renders sorted with language
badges, matches the theme. Live load on prod still needs Gitea CORS
(app.ini [cors] ALLOW_DOMAIN = the docs origin).
Signed-off-by: disqualifier <dev@disqualifier.me>
Make the things that matter stand out, matching the Gitea callout look:
- extra.css: brand-orange warning admonitions (#f57c00, the lambda orange),
hotter danger (#e8590c), blue note/info and cyan tip/example, plus blue
code-annotation markers.
- deploy.md: footgun -> danger callout, secrets -> orange warning, eligible
-> tip; Dockerfile and compose gain numbered code annotations explaining
each magic line; paths/mounts as a table; a restart snippet for rotation.
- workflow.md: warning on setting per-repo git identity before first commit;
tip elevating verify-by-executing.
Verified in-browser: computed border colors match (warning #f57c00,
danger #e8590c), 4 annotation markers render in brand blue, admonition
icons + tinted headers match the Gitea style. mkdocs build --strict clean.
Signed-off-by: disqualifier <dev@disqualifier.me>
- Pull the rethink lambda logo (assets/img/logo.svg) into docs/assets and
wire it as theme.logo + favicon — matches the Gitea brand mark.
- standards.md: fold six thin sections into three fuller ones (Files and
style / Documentation / Quality and error handling), each illustrated
with python snippets, a flake8 output block, Do/Don't tabbed examples,
a traceback, and a log line. Admonitions for the run-it-locally tip and
the lib-logging note.
- libraries.md: add a collapsible 'using a library' example (pyproject
pin + import/usage python snippet).
Verified in-browser: logo renders in the header, snippets/tabs/traceback/
log blocks render against the dark theme, libraries example expands.
mkdocs build --strict clean.
Signed-off-by: disqualifier <dev@disqualifier.me>
Mirror the rethink Gitea theme (data-theme=rethink) on the docs site:
- docs/stylesheets/extra.css maps the exact palette onto Material's slate
scheme: body #0a0f1f, nav #061541, text #eef1f6, primary #569bcc,
accent #55bbff, borders #294274; square corners and blue card/table
borders echoing the Gitea repo panels.
- Force dark-only (drop the light/dark toggle; Gitea is dark-only).
- Rename site to lowercase 'a rethink development' (site_name, copyright,
landing H1).
Verified: mkdocs build --strict clean; rendered landing + content pages
in-browser against the live Gitea page — colors, header bar, links, and
cards match.
Signed-off-by: disqualifier <dev@disqualifier.me>
New docs/workflow.md covering how we actually work day to day:
- why git / why WSL2 (our reasons, links out for generic install)
- signing up on our Gitea (self-serve register, SSH + deploy-key model)
- our git vs public git: per-repo identity, signed commits, develop->main
- our-flavored git basics (everyday loop, commit small/often, gl graph)
- the dev workflow: plan-in-chat / build-in-Claude-Code, tmux split,
claudedo voice control, the .claude/ project convention, AI-assist
habits (git diff | clip.exe)
- recommended setup (WSL + VS Code + Claude Code, pyenv, flake8)
- handy .zshrc/.bashrc snippets with prose on the high-value ones
Claude-first but soft: any AI works, we recommend Claude, and the
.claude/ structure is built on that preference. Sanitized with
placeholders throughout. Nav: Home / Libraries / Standards / Workflow /
Deploy; landing card grid updated.
Verified: mkdocs build --strict clean.
Signed-off-by: disqualifier <dev@disqualifier.me>
Initialize the public Rethink Studios docs site:
- mkdocs.yml: Material theme, light/dark palette toggle, pymdownx
extensions, search, four-section nav skeleton.
- docs/index.md landing page with a card grid.
- Stub index pages for deploy, conventions, libraries, runbooks.
- .gitignore excludes .claude/, site/, and Python build cruft.
Deploy guide deferred; deploy section is a placeholder for now.
Signed-off-by: disqualifier <dev@disqualifier.me>
dsql