From 350884c2b3c2321f86bcf6b3a8ee0140d8ca1f3d Mon Sep 17 00:00:00 2001
From: disqualifier <dev@disqualifier.me>
Date: Wed, 1 Jul 2026 03:04:51 -0400
Subject: [PATCH] deploy: whole-flow as plain text, restore v2 diagram shape;
 admonition variety

- '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>
---
 docs/deploy.md       | 20 ++++++++++----------
 docs/environments.md |  2 +-
 docs/index.md        |  2 +-
 docs/standards.md    |  2 +-
 4 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/docs/deploy.md b/docs/deploy.md
index 6524dbb..7be7515 100644
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -9,11 +9,10 @@
 
 ## Preparing for Deploy
 
-!!! abstract "The whole flow"
-    You build and test locally — leaning on our libraries, AI, and this handbook —
-    then push a branch and merge to `main`. From there the ops tooling takes over: it
-    builds the Docker image and runs it on the fleet. **You don't run any deploy
-    commands** — your only job is the three pieces in the tabs below.
+You build and test locally — leaning on our libraries, AI, and this handbook — then
+push to git. From there the ops tooling takes over: staging (if you run gitflow), then
+it builds the Docker image and runs it on the fleet. **You don't run any deploy
+commands** — your only job is the three pieces in the tabs below.
 
 ```mermaid
 flowchart LR
@@ -29,14 +28,15 @@ flowchart LR
         docs --- local
     end
 
-    build -->|branch| git["git<br/>(Gitea)"]
-    git --> main["main"]
-    main --> deploy["deployment<br/>(ops tooling)"]
-    deploy --> docker["docker<br/>(image built + run on the fleet)"]
+    build -->|push| git["git<br/>(Gitea)"]
+    git -.->|develop, if gitflow| stage["staging"]
+    git --> deploy["deployment<br/>(ops tooling)"]
+    stage --> deploy
+    deploy --> docker["docker<br/>(built + run<br/>on the fleet)"]
 
     classDef ship fill:#061541,stroke:#569bcc,color:#eef1f6;
     classDef work fill:#0e1530,stroke:#294274,color:#eef1f6;
-    class git,main,deploy,docker ship;
+    class git,stage,deploy,docker ship;
     class local,libs,ai,docs work;
 ```
 
diff --git a/docs/environments.md b/docs/environments.md
index c989b08..90b1afb 100644
--- a/docs/environments.md
+++ b/docs/environments.md
@@ -100,7 +100,7 @@ uv sync                     # create/refresh .venv from pyproject.toml + uv.lock
 uv run python -m yourapp    # run inside the managed env, no manual activate
 ```
 
-!!! note "`uv.lock` is local-only — never committed"
+!!! info "`uv.lock` is local-only — never committed"
     `uv sync` writes a `uv.lock` for your machine's resolved environment. It is
     **gitignored**, not committed — we don't ship a lockfile. Pinning happens in
     `pyproject.toml` (below), not the lock.
diff --git a/docs/index.md b/docs/index.md
index 611a86d..5182316 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -8,7 +8,7 @@ infrastructure specifics (hostnames, internal IPs, exact topology, secrets) stay
 out of it; examples use placeholders like `<workspace>`, `<project>`, and
 `/srv/...`.
 
-!!! tip "Point your coding agent here"
+!!! example "Point your coding agent here"
     Want your agent aware of our libraries, standards, and deploy rules before it
     writes a line? Tell it to read this handbook — so it reaches for an existing
     `rethink-public` lib instead of reinventing it, follows our conventions, and
diff --git a/docs/standards.md b/docs/standards.md
index b5b66e5..ebcb287 100644
--- a/docs/standards.md
+++ b/docs/standards.md
@@ -125,7 +125,7 @@ TimeoutError: request timed out after 30s
 2026-06-29 14:03:11,204 WARNING aioweb.session fetch timed out: https://example.test/feed
 ```
 
-!!! note "Logging belongs to the app, not the library"
+!!! info "Logging belongs to the app, not the library"
     Libraries **emit only** — `log = logging.getLogger(__name__)` and nothing
     else. Handlers, levels, and formatting are configured once at the
     application entry point, so a lib never dictates how its host logs.