@@ -1,16 +1,92 @@
11 # Clanker and the Dev
22
3-A Jekyll/GitHub Pages comic-strip blog with deterministic SVG comics generated from markdown seeds.
3+A Jekyll/GitHub Pages comic-strip blog about developers, AI tools, terminal gremlins, and jokes that compile into deterministic SVG comics.
44
5-## Run in Docker
5+The site is mostly markdown. Comic ideas start as small seed files in `comic/inbox/`; `./job.sh` turns a seed into a JSON comic spec and renders a Jekyll post with an inline SVG.
6+
7+## Run locally
8+
9+Local development runs in Docker only, so you do not need to install Ruby gems on your machine.
10+
11+```bash
12+./dev.sh
13+```
14+
15+Then open:
16+
17+```txt
18+http://localhost:4000
19+```
20+
21+The Docker container mounts the repo, so edits to posts, layouts, CSS, and generated comics are reflected by Jekyll.
22+
23+## Generate a comic from an inbox item
24+
25+1. Add a markdown seed to `comic/inbox/`:
26+
27+ ```txt
28+ comic/inbox/my-great-joke.md
29+ ```
30+
31+2. Use this seed format:
32+
33+ ```md
34+ ---
35+ title: My Great Joke
36+ credit: Your Name / handle / inspiration
37+ timestamp: 2026-06-08
38+ ---
39+
40+ 1. Set up the premise.
41+ 2. Escalate the developer pain.
42+ 3. Let Clanker misunderstand everything.
43+ 4. Land the punchline.
44+ ```
45+
46+3. Run the generation job:
47+
48+ ```bash
49+ ./job.sh
50+ ```
51+
52+The job processes the first `*.md` file in `comic/inbox/` alphabetically. It asks Pi to convert the seed into `comic/specs/<slug>.json`, then runs `comic/render-comic.js` to create `_posts/YYYY-MM-DD-<slug>.md`.
53+
54+On success, the seed moves to `comic/done/`. On failure, it moves to `comic/failed/`.
55+
56+## Review and commit a generated comic
57+
58+After running `./job.sh`, inspect the generated files:
59+
60+```bash
61+git status
62+git diff
63+```
64+
65+Run the site locally if you want to preview the strip:
666
767 ```bash
868 ./dev.sh
969 ```
1070
11-Open <http://localhost:4000>.
71+When it looks good, commit the seed, spec, and post:
72+
73+```bash
74+git add comic/done comic/specs _posts
75+git commit -m "Add my great joke comic"
76+```
77+
78+## Contribute your own joke
79+
80+Got a joke about AI coding, burnout, terminals, yak shaving, overconfident bots, or software nonsense? Please send it in.
1281
13-## Posts
82+1. Fork this repo.
83+2. Create a branch.
84+3. Add your joke as a seed in `comic/inbox/`, or run `./job.sh` and commit the generated comic too.
85+4. Open a pull request.
86+
87+Small seeds are welcome. Half-baked ideas are welcome. If the premise is funny, Clanker can probably ruin it.
88+
89+## Manual post format
1490
1591 Jekyll posts live in `_posts/` and use filenames like:
1692
@@ -29,41 +105,23 @@ title: My Strip
29105 Post body goes here.
30106 ```
31107
32-## Comic generation job
108+## Optional chat-script compiler
33109
34-Drop seed markdown files in `comic/inbox/`, then run:
35-
36-```bash
37-./job.sh
38-```
39-
40-The job asks Pi to convert the first inbox seed into `comic/specs/<slug>.json`, then `comic/render-comic.js` deterministically renders an inline SVG Jekyll post at `_posts/YYYY-MM-DD-<slug>.md`.
41-
42-You can also compile a Spittoon-style chat script directly into a spec:
110+You can compile a Spittoon-style chat script directly into a comic spec:
43111
44112 ```bash
45113 node comic/chat-to-spec.js my-strip.chat comic/specs/my-strip.json
46114 node comic/render-comic.js comic/specs/my-strip.json
47115 ```
48116
49-Chat lines look like `dev->clanker: ship it? (curious/helpful) [screen-glow]`. Repeating a speaker starts a new panel, so two alternating speakers can share one panel as dialogue balloons.
50-
51-Seed example:
117+Chat lines look like:
52118
53-```md
54----
55-title: The Cycle of AI Coding Burnout
56-credit: Ian for the original joke
57-timestamp: 2026-06-08
58----
59-
60-1. wow
61-2. WOW
62-3. HOLY SHIT!
63-4. **dead**
64-5. Let's open nvim...
119+```txt
120+dev->clanker: ship it? (curious/helpful) [screen-glow]
65121 ```
66122
123+Repeating a speaker starts a new panel, so two alternating speakers can share one panel as dialogue balloons.
124+
67125 ## GitHub Pages
68126
69-The site is a standard Jekyll project. Configure GitHub Pages to build from the repository branch, and GitHub will run Jekyll automatically.
127+This is a standard Jekyll project. Configure GitHub Pages to build from the repository branch, and GitHub will run Jekyll automatically.