diff --git a/.rulesync/skills/blog-images/SKILL.md b/.rulesync/skills/blog-images/SKILL.md index 5cb72f2..e1717c6 100644 --- a/.rulesync/skills/blog-images/SKILL.md +++ b/.rulesync/skills/blog-images/SKILL.md @@ -39,7 +39,7 @@ There is no image-per-word quota. Add a visual when it explains, substantiates, ## Direct and make -Read [style.md](references/style.md) for the author-selected **editorial cut-paper** treatment, richer narrative composition, broader palette, reference strategy, and allowed variation. The selected material anchor is `assets/cut-paper-reference.png`; `assets/cut-paper-scene-reference.webp` demonstrates the current grounded scene treatment. Read [prompts.md](references/prompts.md) when preparing generation or editing briefs. For dimensions, crop geometry, social typography, accessibility, and exports, read the relevant sections of [production.md](references/production.md). The project's `docs/blog-images-research.md` records the research behind these choices. +Read [style.md](references/style.md) for the author-selected **editorial cut-paper** treatment, richer narrative composition, broader palette, reference strategy, and allowed variation. The selected material anchor is `assets/cut-paper-reference.png`; `assets/cut-paper-scene-reference.webp` demonstrates the current grounded scene treatment. Read [prompts.md](references/prompts.md) when preparing generation or editing briefs. For dimensions, crop geometry, social typography, accessibility, and exports, read the relevant sections of [production.md](references/production.md). Use **GPT Image 2** (`gpt-image-2`) for conceptual bitmap art, as requested by the author, following the installed `imagegen` skill. Select the model through an exposed model control; writing its name in a prompt does not select it. When the built-in tool cannot verify the model, the bundled CLI supports explicit `--model gpt-image-2` and requires a locally configured `OPENAI_API_KEY`. Do not claim an unverified backend is GPT Image 2 or silently substitute another model. The author has explicitly authorised the built-in generator for this workflow even when its backend model is unverified; use it directly unless they restore a strict model requirement. Keep GPT Image 2 as the preferred model when selection is exposed. Use native editable sources for diagrams and exact typography. @@ -51,7 +51,7 @@ Use text sparingly. Default to letting action, gesture, objects, and composition ## Integrate and review -Save selected assets inside the project and preserve editable sources or generation briefs. For a post receiving new artwork, keep compact production notes at `docs/blog-images/.md` outside the imported article tree with the final prompts, reference roles and paths, style version, actual output dimensions, capture/source attribution, and placements. Do not store rejected generations or private captures in the published content directory. Copying an asset should not silently replace unrelated existing artwork. +Save final selected assets in the project. Keep per-post prompts, generation settings, research, and production briefs transient; do not create repository notes or archives unless explicitly requested. Keep reusable style guidance in this skill. Do not store rejected generations or private captures in the published content directory. Copying an asset should not silently replace unrelated existing artwork. Use the site's normal image/figure support, its existing spacing, and natural aspect ratios. Add useful captions and context-sensitive alt text. Keep the author's title, slug, dates, claims, and draft status unless the request includes changing them. diff --git a/.rulesync/skills/blog-images/references/production.md b/.rulesync/skills/blog-images/references/production.md index d4c1f5e..17c2b17 100644 --- a/.rulesync/skills/blog-images/references/production.md +++ b/.rulesync/skills/blog-images/references/production.md @@ -96,7 +96,7 @@ Before integrating a custom card, inspect: - `src/app/(blog)/blog/[slug]/page.tsx`: explicitly declares the share-image URL for both social fields and BlogPosting's image. - The adjacent `opengraph-image.tsx` and `twitter-image.tsx` routes: also generate file-based metadata. Resolve their interaction by examining final HTML; don't assume adding `twitter-image.png` alone selects it everywhere. Framework metadata precedence and version changes make source filenames insufficient evidence. [Next metadata documentation](https://nextjs.org/docs/app/api-reference/functions/generate-metadata). -Keep Markdown production notes in `docs/blog-images/.md`, outside `src/content/blog`. The current broad dynamic imports enumerate the article tree; a co-located `image-notes.md` is picked up as an unsupported module by a fresh Turbopack compile. Keep only runtime article modules and supported assets there. +Keep only runtime article modules and supported assets in `src/content/blog`. Its broad dynamic imports can pick up co-located Markdown notes as unsupported modules. Do not persist transient image-production notes elsewhere in the repository either. Keep one custom 1200 × 630 image by default. Do not invent `metadata.hero`, `metadata.ogImage`, or an artwork prop on the fallback renderer. A custom static file is the smallest existing override for finished art. A requested deterministic illustrated card may use the existing co-located image-module convention; reuse the renderer's treatment without redesigning all articles. diff --git a/.rulesync/skills/blog-images/references/prompts.md b/.rulesync/skills/blog-images/references/prompts.md index dc07da5..393dccf 100644 --- a/.rulesync/skills/blog-images/references/prompts.md +++ b/.rulesync/skills/blog-images/references/prompts.md @@ -1,6 +1,6 @@ # Briefs and prompting recipes -These are original templates for this blog, informed by the project's `docs/blog-images-research.md`. Fill them from the finished post. Use GPT Image 2 (`gpt-image-2`), selected through the generation interface rather than named only in the prompt. They are instructions for the assistant/art director; send only the relevant visual brief to the image generator, not the entire publishing checklist. +These are reusable templates for this blog. Fill them from the finished post. Use GPT Image 2 (`gpt-image-2`), selected through the generation interface rather than named only in the prompt. They are instructions for the assistant/art director; send only the relevant visual brief to the image generator, not the entire publishing checklist. ## Plan visuals from a finished article @@ -106,5 +106,3 @@ For a local defect, make a local edit. If the whole result has drifted into a di ## Review the set, not just the individual images > Compare [selected images] beside the accepted house reference at the same displayed width. Check palette temperature, paper-edge character, shadow depth, texture density, viewpoint, and visual complexity. Then inspect each at its actual article/social size. Report only specific defects and correct those that affect meaning, readability, or family resemblance. Keep deliberate differences in subject and framing. Do not continue generating variants after the requirements pass. - -Save the final brief and reference identities in the post's production notes under `docs/blog-images/`, with the selected asset path. If the tool exposes model/version/settings, record them; otherwise mark them unavailable. Keep a short reason for any deliberate style exception so the next post does not accidentally adopt it as the new default. diff --git a/.rulesync/skills/blog-images/references/style.md b/.rulesync/skills/blog-images/references/style.md index 21e7864..7281d16 100644 --- a/.rulesync/skills/blog-images/references/style.md +++ b/.rulesync/skills/blog-images/references/style.md @@ -48,7 +48,7 @@ Judge the scene before judging its finish. Could a reader describe the visible a 3. Keep the stable style paragraph below in each prompt. Vary only the article-specific scene and its composition. 4. For a local defect, edit the selected result while stating what must remain. For later posts, return to the original accepted anchor rather than repeatedly inheriting an imperfect edit. 5. Compare the new image and reference at equal displayed widths. Check material, temperature, shadows, focal hierarchy, and complexity. Inspect the mobile version before adding detail. -6. Record the style version, reference path, final brief, actual dimensions, and generation route in `docs/blog-images/.md`. Change this guide when the author establishes a new recurring preference. +6. Update this guide when the author establishes a new recurring preference; keep per-image decisions transient. A seed is not a style system. References improve repeatability but do not guarantee identical rendering across models or versions. Reuse an existing piece of artwork when exact identity matters. diff --git a/.rulesync/skills/blog-writing/SKILL.md b/.rulesync/skills/blog-writing/SKILL.md index 5b6df7e..aa204d6 100644 --- a/.rulesync/skills/blog-writing/SKILL.md +++ b/.rulesync/skills/blog-writing/SKILL.md @@ -7,6 +7,8 @@ description: Write and revise Sid Jain's personal technical blog posts in his vo Write a personal account of something the author did, noticed, or came to understand. The prose should reward reading, with the curiosity and specificity of a conversation between people who build things. Accuracy belongs in the editing process; the article should not sound like testimony about what a repository proves. +For Sid's repository, keep research reports, per-post prompts, and production briefs transient unless explicitly requested. Do not create a research archive; reserve `docs/` for maintained implementation and usage documentation. + ## Find the material that can carry a story Read the draft, the author's context, and the relevant artifacts. Find the human reason for the work and the discovery worth telling. Preserve the author's anecdotes, opinions, jokes and turns of phrase where they work. When context is missing, ask the smallest question that would reveal what happened or what surprised them; don't require an interview when the supplied material already carries the story. diff --git a/.rulesync/skills/site-seo/SKILL.md b/.rulesync/skills/site-seo/SKILL.md index c150505..7a99b41 100644 --- a/.rulesync/skills/site-seo/SKILL.md +++ b/.rulesync/skills/site-seo/SKILL.md @@ -7,6 +7,8 @@ description: Audit and improve website and blog search discoverability, metadata Make the site's content easy to find, understand, share and cite. Reuse its content model, metadata APIs, image renderer, feeds and deployment checks. Pair with `blog-writing` for Sid's articles; search optimisation should support the personal narrative. +For Sid's repository, keep research reports, per-post prompts, and production briefs transient unless explicitly requested. Do not create a research archive; reserve `docs/` for maintained implementation and usage documentation. + ## Select the relevant checks - **Publishing an article:** final title/description, author/dates, representative social image, article schema, internal links, feeds, sitemap and alternate content. Read [publishing.md](references/publishing.md). diff --git a/BLOG.md b/BLOG.md index 4654fb8..a28dd3c 100644 --- a/BLOG.md +++ b/BLOG.md @@ -7,9 +7,9 @@ publication checks. Both include reusable prompts and researched references. For images on an already-written post, use the [blog-images skill](.rulesync/skills/blog-images/SKILL.md). It covers image selection, exact insertion points, a shared illustration style, generation -prompts, and desktop/mobile/social crops. Its -[practitioner research](docs/blog-images-research.md) -extends the earlier writing research with actual AI-media workflows. +prompts, and desktop/mobile/social crops. Keep research reports, per-post image +prompts and production briefs transient; do not commit them to the repository. +Reserve `docs/` for current implementation and usage documentation. Public identity URLs always use `https://f0rr0.dev`; preview deployments return `noindex`. The sitemap lists intended search destinations, while alternate @@ -157,5 +157,4 @@ Canonical URLs are derived from Vercel system environment variables when deploye RSS, sitemap and Markdown export after deployment. Article publication does not automatically include sending social posts or email. -The [research landscape](docs/blog-writing-landscape.md) explains the workflow -choices; the skill includes [starting prompts](.rulesync/skills/blog-writing/references/prompts.md). +The writing skill includes [starting prompts](.rulesync/skills/blog-writing/references/prompts.md). diff --git a/docs/blog-elements-2026.md b/docs/blog-elements-2026.md deleted file mode 100644 index ae1bbd9..0000000 --- a/docs/blog-elements-2026.md +++ /dev/null @@ -1,57 +0,0 @@ -# Blog element design inventory — 2026 - -Compared 15 component variations across 8 libraries, with 2026 introduction or redesign evidence. Dates refer to these implementations, not the invention of their underlying UI patterns. Screenshots were captured from live demos on 7 September 2026. Visual judgments below are our assessment, not claims made by the libraries. - -## Evidence and visual comparison - -| Variation | 2026 evidence | Visual assessment | Decision | -| --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| [Rare UI — accent-derived, frameless code](https://www.rareui.com/components/codeblock) | [2026-07-14](https://github.com/swamimalode07/rare-ui/commit/28e385c14688b1ab188947fee0068956064e9f00) — Component introduction commit | The code dominates; a small copy icon floats at the upper right. The orange ramp is distinctive, with very quiet line numbers. | Adopt compact icon controls and restrained highlighting. Keep this site’s existing syntax palette and language tooltip. | -| [Beautiful UI — compact file header](https://www.beautifului.dev/#code-block) | [2026-07-17](https://github.com/slev12397/beautiful-ui/commit/d12f57ecdd8d4e0218127738c56da8d1a2b9e78b) — 17-primitives introduction commit | Compact line height, thin border, quiet filename and copy control; code and diff share one frame. The gray background is lighter than this blog needs. | Adopt compact metadata and border restraint; use a darker background and omit the extra demo frame. | -| [jal-co/ui — labelled code panel](https://ui.justinlevine.me/docs/components/code-block) | [2026-03-12](https://github.com/jal-co/ui/commit/ab6a470faee161afd9b2e964827c5cff4ff43220) — Initial registry component commit; followed old path through its March 30 move | Small language icon, deep black code surface, separate header. Rounded framing is clear, but the header occupies much of a short example. | Adopt the dark surface and language icon; remove the header divider and keep its vertical padding small. | -| [jal-co/ui — single-line code](https://ui.justinlevine.me/docs/components/code-line) | [2026-03-12](https://github.com/jal-co/ui/commit/ab6a470faee161afd9b2e964827c5cff4ff43220) — Initial registry component commit | A short snippet and copy icon fit in one shallow row. It avoids a mostly empty header above a command. | Keep the compact copy control; use the same header layout for short and long fences. | -| [Spectrum UI — expandable code](https://ui.spectrumhq.in/blocks/ai-assistants#code-block) | [2026-07-31 / 08-01](https://ui.spectrumhq.in/changelog) — July 31 AI Assistant block launch; implementation merged August 1 | Near-black body, compact file header, subdued syntax, optional numbers. A bottom “more lines” control contains long output. | Adopt its dark tonal restraint. The bottom expansion strip conflicts with the requested design; do not carry it over. | -| [Shadcn Space — default file block](https://shadcnspace.com/components/code-block) | [2026-06-09](https://github.com/shadcnspace/shadcnspace/commit/748f22179a207f45a625792e35470c4dfe2d7acc) — Code block variants introduction commit | Light body, soft filename header, right-aligned copy icon, modest radius. The saturated red/blue syntax feels louder than the surrounding text. | Keep light mode neutral and compact; retain the blog’s softer syntax colors. | -| [Shadcn Space — scrollable code](https://shadcnspace.com/components/code-block) | [2026-06-09](https://github.com/shadcnspace/shadcnspace/commit/748f22179a207f45a625792e35470c4dfe2d7acc) — Code block 02 introduction commit | A bounded viewport keeps a long listing manageable while the filename and copy action remain available above it. | Retain bounded scrolling for GitHub excerpts and horizontal scrolling for long lines; keep ordinary examples fully readable. | -| [Shadcn Space — multi-file tabs](https://shadcnspace.com/components/code-block) | [2026-06-09](https://github.com/shadcnspace/shadcnspace/commit/748f22179a207f45a625792e35470c4dfe2d7acc) — Code block 05 introduction commit | Filenames double as tabs; a thin underline marks the selected file, and one copy action serves the active file. | Useful when an article needs alternative files in one slot. Current posts use independent examples, so no new tabs were added. | -| [Motion UI — inline install control](https://motion.dev/ui/cta-sections) | [2026-07-23](https://motion.dev/magazine/introducing-motion-ui) — Dated launch of the new Motion UI library, distinct from the older Motion engine | The documentation preview puts its install command and copy icon in one thin row. The surrounding promotional demo is much more expressive. | Adopt command/action proximity and semantic theme tokens. Keep the article’s controls visually quiet. | -| [Motion UI — rolling button label](https://motion.dev/ui/buttons) | [2026-07-23](https://motion.dev/magazine/introducing-motion-ui) — New Motion UI library launch; current rolling-text section visually inspected | The label moves inside a stable pill boundary. Motion is triggered by interaction, with a clear static resting state. | Keep copy feedback in a stable-size control. Use a short color transition and copy/check feedback; no rolling text in a reading surface. | -| [Beautiful UI — flowchart nodes](https://www.beautifului.dev/#flowchart) | [2026-08-13](https://github.com/slev12397/beautiful-ui/commit/f13a45dedb3e2b3ce4d830199129a8603ff63674) — Flowchart primitive introduction commit | Readable node labels and compact status chips separate structure from meaning. A dotted editor canvas and nested frames make the demo feel like a tool. | Adopt readable labels and subdued surfaces. Keep Mermaid’s reading canvas plain and use the site’s shared colors. | -| [Bklit UI — monochrome Sankey](https://bklit.com/docs/components/sankey-chart) | [2026-01-28](https://github.com/bklit/bklit-ui/commit/1738b6ec3355a508c0320b667fdea6a9f3e72860) — Sankey v1 introduction commit | Grayscale links and nodes avoid a default rainbow palette. At the inspected desktop size, vertical labels overlap in the preview. | Adopt tonal consistency; preserve natural diagram width and scrolling so labels never need to be squeezed into the article width. | -| [jal-co/ui — repository card](https://ui.justinlevine.me/docs/components/repo-card) | [2026-03-29](https://github.com/jal-co/ui/commit/b992cf66ab25f326d471a49845c210d1753cc6a8) — Batch 1 release introducing repository card | Repository name leads in readable sans-serif type. Description and compact metadata follow, with minimal surface contrast and no large brand illustration. | Keep compact metadata; use GitHub’s Octicons and familiar metadata layout, with restrained state accents. | -| [Oat — semantic typography and quote](https://oat.ink/components/typography/) | [2026-01-16](https://github.com/knadh/oat/commit/376c97b6305ec87dc65b9405cfb0c2d1b5157ed8) — Initial documentation implementation; repository created January 15, 2026 | The quote is just text and a muted side rule. Its heading specimen exposes a clear size hierarchy rather than making every level identical. | Adopt the quiet rule and distinguish subsections. Keep quotes upright for longer technical passages. | -| [Shadcn Space — aspect-ratio image variants](https://shadcnspace.com/components/aspect-ratio) | [2026-08-18](https://shadcnspace.com/changelog) — Version 2.2.6 explicitly introduced six Aspect Ratio variants | Real photography makes cropping and proportions easy to assess. Modest radii work well; overlay captions compete with some images. | Adopt real local/remote photos, reserve known dimensions, keep captions below images, and constrain portrait screenshots. | - -## Applied to this blog - -- All fenced blocks use one consistent compact header: language icon with a hover/focus tooltip, copy icon, and no divider or footer. -- Code surfaces use the existing dark background token; highlight fills are subdued, and copy feedback stays in a fixed-size icon control with an accessible label. -- Shared article tokens govern article borders, surfaces and controls. GitHub previews use the site’s card, text and border tokens; GitHub identity comes from Octicons and metadata layout, with color limited to status icons, language dots and diff counts. Mermaid reads its colors from those tokens rather than maintaining a second palette. -- Blockquotes use a muted side rule. Subheadings have a clear hierarchy. GitHub card titles use readable sans-serif type. -- Photos and screenshots have modest radii, no decorative shadows, natural dimensions and captions beneath them. The kitchen sink contains actual relative and remote photographs. - -## Kitchen sink coverage - -Typography (headings 2–6, emphasis, deletion, inline code, line breaks, horizontal rules); nested ordered/unordered/task lists; simple/multiparagraph/nested quotes; highlighted lines and words, short/long/unlabelled fences; relative and remote images, optimized figures, portrait screenshots, paired screenshots, SVG and an opt-in GIF disclosure; all three supported GitHub embed types (repository, PR and pinned code excerpt), plus a card grid and ordinary inline GitHub link; aligned tables; every Mermaid family used in existing posts (flowchart, ELK flowchart, sequence, state); internal/external/anchor/autolinks, localized dates and repeated/multiparagraph footnotes. - -## Research boundaries - -GitHub repository discovery was followed by file-level commit histories; file moves were traced to their earlier paths. Spectrum’s original 2024 library was not counted as a 2026 launch: its dated 2026 AI Assistant block release qualifies the inspected variation. Rare UI here is Swami Malode’s rareui.com, not the unrelated rareui.in project. Beautiful UI is the project behind the user’s beautiful-ui-five.vercel.app link. - -Also screened BagUI, Canvas UI, Appica and Bezel through GitHub discovery. Their existence or repository creation alone was not used to pad the comparison. Attempts to open linked X posts returned HTTP 403; launch/date evidence above therefore comes from accessible first-party release notes and GitHub histories. Older libraries appearing in 2026 roundups, and older blog designs with only a 2026 article date, were excluded. - -No component library was installed or its implementation copied; official MIT-licensed Octicon paths are shared locally with their license retained, and the changes adapt visual principles to the existing components. - -## Validation - -Browser checks passed in dark and light themes at desktop width, with overflow checks at 320, 390 and 768px. Copy returned the actual code; Mermaid zoom, reset and fullscreen worked. All four diagram specimens rendered without errors, along with four GitHub cards and one pinned source excerpt. Focused tests cover code structure, image dimensions, GitHub URL parsing, PR states and escaped remote content. Lint and TypeScript checks passed. - -## GitHub identity and spacing review - -Compared the live [Next.js repository](https://github.com/vercel/next.js), [ZeroClaw pull request](https://github.com/zeroclaw-labs/zeroclaw/pull/3086), and [Primer StateLabel](https://primer.style/product/components/state-label/) separately from the 2026 inventory. These established GitHub conventions are included in response to the explicit request for recognizable GitHub embeds; they are not counted as newly launched 2026 designs. - -Repository previews now use the repository Octicon, neutral repository name, visibility label, language dot, stars and forks. Pull requests put their number beside the title and use neutral badges with the correct colored Octicon for open, draft, closed and merged states. Every preview carries the GitHub mark. The misleading “issues” total was removed because GitHub’s repository API count includes pull requests. - -Code frames use a 16px outer content inset: 16px horizontal code padding and 16px bottom padding. Header icons sit 16px from the top and side edges (8px toolbar inset plus 8px within each 32px control). The toolbar has matching 8px top and bottom padding, and the code has no top padding, so spacing does not stack at the join. Controls keep 16px icons, 4px gaps and 4px radii inside the shared rounded frame. Source links take their content width, truncate on small screens and underline on hover; they do not acquire a stretched button background. Language indicators use a normal cursor and the same tooltip component as copying. No negative margins or one-line layout exception remain. Diagram controls use the same spacing increments. - -GitHub preview typography uses two levels: 14px medium for the repository path and PR title, and 12px regular for metadata. Repository descriptions use regular 14px body text. Owner/repository segments, PR numbers, authors, badges and diff counts no longer introduce their own weight changes; small color accents identify status and changes. diff --git a/docs/blog-images-research.md b/docs/blog-images-research.md deleted file mode 100644 index 77b4f11..0000000 --- a/docs/blog-images-research.md +++ /dev/null @@ -1,143 +0,0 @@ -# Research: consistent AI imagery for a personal technical blog - -Researched September 8, 2026. This review follows the image-related leads in the repository's earlier writing/SEO research, then expands into firsthand publishing workflows, inspectable generation code, design systems, and current platform documentation. The operational decisions live in [the skill](../.rulesync/skills/blog-images/SKILL.md), [style.md](../.rulesync/skills/blog-images/references/style.md), [prompts.md](../.rulesync/skills/blog-images/references/prompts.md), and [production.md](../.rulesync/skills/blog-images/references/production.md). - -## What was already in the repository - -Initially inspected `origin/next` at `d9c99bc99c7eb54089a19b6747298d4bbf26022d`, then refreshed the working branch to `50db6fb956d997889c05a0080a74f81f07c1e447`. The intervening `9174563` moved research out of skill references and into `docs`; this report follows that convention. Its preceding commit `84ca332` introduced the recent writing/SEO work. The remote has no `main`; `master` at `0dd47f41a0073b5e9b60f0b2b4596824c3f8bd58` contains the historical static site. The useful current research is on `next`: - -- `docs/blog-writing-landscape.md`: actual writers and public workflows, useful visual roles, Every's writing toolkit, Opalic's diagrams/screenshots, Satori, Excalidraw, and an inspected cover-generator implementation that was still a TODO at the earlier review. -- `docs/site-seo-landscape.md` and the `site-seo` references: metadata, image accessibility, representative search/social images, responsive rendering, and publication checks. -- `docs/blog-elements-2026.md` and `BLOG.md`: current article components and publishing mechanics. -- `.rulesync/skills/blog-writing/references/prompts.md`: a compact visual brief, but no maintained illustration style or complete image-selection workflow. -- `src/lib/blog-share-image.tsx`: the existing 1200 × 630 cream/charcoal/amber title card, with 82 px horizontal and 72 px vertical padding. -- `src/components/blog/article-prose.tsx`, `src/components/mdx/MDXImage.tsx`, and `src/components/mdx/Mermaid.tsx`: natural-ratio images, figure/caption spacing, screenshot grids, static imports, and theme-aware diagrams. - -The gap was art direction across posts and the process from a finished article to selected subjects, precise insertion points, prompts, and inspected final crops. There was no need for another publishing platform or image service. - -## What established publishers and practitioners actually do - -“Successful” needs a useful definition here: observable sustained publishing and an inspectable working technique. These sources do **not** establish that AI illustrations caused audience growth. Public demonstrations, reported production workflows, and product documentation are different kinds of evidence. Some commercial guides overstate repeatability; their transferable techniques are retained without those guarantees. - -### Lucas Crespo / Every: art direction is a repeatable editorial practice - -Every's creative lead explicitly says the publication relies on Midjourney for article imagery and that his guide began as internal documentation. His accessible guide recommends exploring simple concepts before narrowing with detail. The article still contains old interface instructions despite an updated date, so it is evidence of a workflow, not a current setup manual. Only the accessible portion was used. [Firsthand guide](https://every.to/p/a-definitive-guide-to-using-midjourney). - -There are inspectable published results: the MoviePass/COGS article credits Crespo and exposes a cover prompt built around isolated mechanical cogs with a vintage cross-hatched treatment. This connects a specific editorial idea, a visual medium, and a real article rather than merely promising “on-brand images.” [Published cover and prompt credit](https://every.to/napkin-math/cogs-how-i-bankrupted-moviepass-c6535dbb-3ea2-4329-ac3e-1249415ae81b). - -In his firsthand Flora review, Crespo values keeping alternatives visible together, refining them, and combining useful parts instead of repeatedly starting over in disconnected apps. That is useful even without adopting Flora: compare candidates in one view and retain the selected direction. The piece is a designer's product review, not evidence that Every generates every cover with Flora. [Canvas workflow](https://every.to/source-code/when-an-ai-tool-finally-gets-you). - -**Adopt:** article-specific visual concepts, a stable treatment, visible comparisons, targeted refinement. **Do not import:** Every's exact aesthetic, its old tool instructions, or a mandatory stack of design applications. - -### Daniel Nest / Why Try AI: short style controls, concrete subjects - -Nest's recurring illustrated newsletter demonstrates several subjects under the same short medium descriptor and publishes its own featured-image prompt. His February 2024 examples make differences such as continuous linework, risograph, and flat illustration easy to compare. These are public experiments by an active publisher, not comparative audience tests. [Illustration examples](https://www.whytryai.com/p/best-midjourney-prompts-february-2024). - -His style-reference demonstration keeps a spaceship subject while transferring the appearance of a separate cartoon reference, and contrasts it with the unintended content mixing of a normal image prompt. That makes “reference for style” versus “reference for subject” a concrete production distinction. The examples use an older Midjourney version. [Style-reference demonstration](https://www.whytryai.com/p/10x-ai-37-bard-upgrades-midjourney-niji-6). - -**Adopt:** separate subject from style, inspect what the reference actually controls, avoid sprawling contradictory prompt modifiers. **Do not import:** old parameters without checking the current provider or another creator's signature treatment. - -### Ryan Brown / stylegen: preserve the recipe alongside the image - -Brown describes using pixel art for his blog and publishes reference images, outputs, and a CLI. The inspected implementation loads real reference-image bytes, adds a style instruction, reads reusable prompts from files, and saves a JSON sidecar separately from the image. It also supports generating candidates. This is source-visible mechanics; it is not evidence of large readership or better SEO. [Repository and examples](https://github.com/ryanbbrown/stylegen), [inspected implementation](https://github.com/ryanbbrown/stylegen/blob/main/sgen.py). - -**Adopt:** keep the final prompt and reference identity in a text file that a future agent can read; retain a selected reference; generate a small candidate set when concept selection benefits. **Do not import:** another API wrapper, its price assumptions, mandatory parallel generation, or its pixel-art identity. A Markdown note and the available image tool cover this blog's needs. - -### Allen Finn / Skio: generate reusable pieces, then compose exact covers - -Finn reports that generating complete covers caused mascot and typography variation. His replacement was to generate 16 mascot variants once, store them as assets, and use a small Pillow compositor for the background, exact font, wrapping, and placement. He frames the problem as 2,438 covers and reports a newly working pipeline; the post does not independently prove that every one was generated or that they improved traffic. [Firsthand production account](https://www.linkedin.com/posts/allenfinn_how-do-you-generate-2438-blog-post-cover-activity-7435029405594427394-U_uh). - -**Adopt:** stable reusable artwork for recurring motifs and deterministic typography. **Do not import:** a mascot that Sid did not request, a 16-image prerequisite, their Python/cloud/Notion pipeline, or their claims about other tools' current limitations. Sid already has ImageResponse. - -### Dom Kirby: imagery is part of finishing the actual article - -Kirby describes Gemini/Nano Banana for recent graphics and infographics, Canva for more directed graphics, and using the final article's context when preparing its publication/distribution material. This confirms a working personal-blog practice. He reports better speed and output, without a measured improvement attributable to the images. [Blogging workflow, especially “Graphics”](https://domkirby.com/blog/ai-assisted-blog-writing-workflow/). - -**Adopt:** create graphics from the settled article and inspect them before publication. **Do not import:** obligatory model switching, an AI-generated infographic when verified diagram source is better, or a Canva dependency. - -### Alexander Opalic: AI-assisted media includes diagrams and real captures - -Opalic demonstrates explanation → Mermaid source → revision, and separately publishes a browser skill that captures real pages with annotations. These are useful technical-blog media workflows with concrete artifacts, even though they do not establish a cross-post raster-art style. [Diagram workflow](https://alexop.dev/posts/how-to-use-ai-for-effective-diagram-creation-a-guide-to-chatgpt-and-mermaid/), [screenshot workflow](https://alexop.dev/posts/app-screenshots-claude-code-skill/). - -**Adopt:** use AI to choose and author a diagram or focus a screenshot, with native data/text preserved. **Do not import:** capturing every page, rigid annotation quotas, or a second browser stack. The existing session diagram and Telegram captures in Sid's posts already do these jobs. - -### Jordan Hong Tai: one style paragraph plus an inspected reference library - -Hong Tai publishes a style block, a same-subject comparison, and a workflow that saves selected images and their prompts for later reference. The guide uses Higgsfield and discloses an affiliate link. Its guarantees of zero drift and its rule against all editing are stronger than the demonstration supports. [Guide and comparison](https://www.jordanhongtai.com/guides/consistent-ai-brand-images). - -**Adopt:** persistent reference images plus a reusable text block. **Modify:** keep a stable original anchor so recursive reuse does not gradually drift; edit local defects and restart only when the overall direction is wrong. **Do not import:** exact-colour guarantees from hex codes or another subscription. - -### A useful counterexample: Victoria Lo's consistency is not AI - -Lo explicitly says her covers are made with Photoshop and reused design elements, and describes the linked piece as her 242nd post. She uses illustration libraries and an established routine. A reader's assumption that consistent covers must be AI-generated was incorrect. [Her account](https://lo-victoria.com/why-i-dont-ai-generate-my-blog-images). - -**Adopt:** consistent composition and reusable elements are independent of the generation tool. **Do not claim:** that a polished blogger uses AI based only on the visual appearance of their work. - -## Practical techniques translated into this skill - -| Technique | Application here | When it is useful | -| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -| Separate concept selection from rendering | Write two or three brief visual directions, choose the one tied to the article's discovery, then render | When the author supplied a topic but no clear scene | -| Hold style constant and vary subject | Stable paragraph plus actual reference image; article-specific action and objects | Every subsequent illustration in the series | -| Separate reference roles | Identify style, object identity, composition sketch, and edit target explicitly | Prevents copying an irrelevant subject or accidentally editing a reference | -| Keep the best source as the anchor | Return to the original selected reference after accumulated drift | Across posts and multiple editing sessions | -| Compare at equal displayed size | Side-by-side review of colour, line weight, texture, and complexity | A set can be inconsistent even when every image looks good alone | -| Generate reusable components only when they recur | Reuse a selected motif; compose exact titles with native layout | Repeated identity elements or a regular social-card format | -| Reserve space before generation | Specify the real title box or crop-safe object area in the brief | Prevents rescuing a beautiful but unusable social image later | -| Change one thing at a time | Target a local defect; preserve the remaining selected image | Keeps iteration understandable and limits unnecessary generations | -| Keep a readable recipe | Per-post notes with final prompts, sources, references, settings when exposed, and actual dimensions | Makes the next session reproducible without relying on chat history | -| Simplify for the smallest view | Preview thumbnail before adding details; prefer large silhouettes | Desktop artwork otherwise often becomes illegible on phones | - -These are practical adaptations, not controlled claims that any one recipe improves clicks. The skill deliberately avoids a required image count, global fine-tuning, mass generation before articles exist, and an automatic generation/rejection loop. A completed post supplies better subjects than a generic stock library. - -## Provider controls that support the techniques - -- **Midjourney:** its current Style Reference documentation distinguishes style from objects, offers reference influence controls, and warns that older style codes can change between versions. Use those controls only if the author chose Midjourney; do not paste `--sref` or `--sw` into an unrelated tool. Record the version and chosen references. [Official Style Reference guide](https://docs.midjourney.com/hc/en-us/articles/32180011136653-Style-Reference). -- **Seeds:** the provider explicitly says seeds do not store a visual style across different prompts. They can help controlled experiments but are not the persistence mechanism for the blog. [Official seed guidance](https://docs.midjourney.com/hc/en-us/articles/32604356340877-Seeds). -- **Recraft:** custom styles can be built from reference images and revised by changing the reference mix. A saved style is useful when a team already uses that product. This is a documented capability, not a reason to install it for one blog. [Custom-style documentation](https://www.recraft.ai/docs/recraft-studio/styles/custom-styles/how-to-create-a-custom-style). -- **Gemini:** the official image documentation supports reference-guided generation and using previous images for consistency. Transfer the general method, not provider-specific limits or advertised quality claims. [Image documentation](https://ai.google.dev/gemini-api/docs/image-generation). -- **Current local tool:** the installed `imagegen` skill supports a built-in tool, labelled reference roles, and targeted edits. Its actual callable schema takes precedence over older skill examples. The author selected **GPT Image 2** (`gpt-image-2`). The bundled CLI can select it explicitly; the built-in tool currently exposes no model selector. Record the actual route and model evidence; a model name in a prompt does not select the backend. - -## Design, accessibility, and delivery evidence - -| Source | What it supports | Decision | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -| [IBM illustration principles](https://www.ibm.com/design/language/illustration/overview/) and [composition guidance](https://www.ibm.com/design/language/illustration/tips-and-techniques/) | A repeatable visual grammar, clear purpose, and different detail levels for different roles | Define medium, palette, contours, viewpoint, and density together; don't copy IBM's brand | -| [Julia Evans on useful programming comics](https://jvns.ca/blog/2020/12/05/how-i-write-useful-programming-comics/) | Choosing useful things to explain matters more than sophisticated drawing tools | Start with the insight the reader needs to see | -| [NN/g image eyetracking research](https://www.nngroup.com/articles/photos-as-web-content/) | Relevant information attracts attention; decorative filler can be ignored | No automatic section-divider or image-per-word quota; research was not an AI-blog traffic experiment | -| [Open Graph protocol](https://ogp.me/) | Image URLs and their descriptive metadata | Fetch real bytes and inspect the emitted tags; OG defines no universal padding rectangle | -| [LinkedIn sharing requirements](https://www.linkedin.com/help/linkedin/answer/a521928/making-your-website-shareable-on-linkedin) | Its sharing module's aspect, dimensions, and file limit | Keep the existing 1200 × 630 export; accommodate an exact destination brief when requested | -| [Google image guidance](https://developers.google.com/search/docs/appearance/google-images) | Relevant nearby text, meaningful image alternatives, crawlable image elements, and representative imagery | Place figures beside their explanation; don't substitute a generic logo for article art | -| [Discover guidance](https://developers.google.com/search/docs/appearance/google-discover) | Large representative images and a considered landscape crop | Treat a text-heavy social title card and search art as separate editorial decisions | -| [WAI image tutorial](https://www.w3.org/WAI/tutorials/images/) | Alternatives depend on image purpose | Describe meaning; provide nearby explanations for complex visuals | -| [WCAG text contrast](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) and [graphical contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) | Legibility requirements for meaningful information | Check rendered size and adjacent colours, not only source pixels | -| [web.dev responsive art direction](https://web.dev/learn/images/prescriptive) and [LCP](https://web.dev/articles/optimize-lcp) | Source selection and loading should match the actual slot | Native responsive delivery; reserve dimensions and don't lazy-load the principal above-fold image | -| [Next ImageResponse](https://nextjs.org/docs/app/api-reference/functions/image-response) and [metadata](https://nextjs.org/docs/app/api-reference/functions/generate-metadata) | Deterministic social rendering and framework metadata behaviour | Reuse the existing pipeline and inspect final output instead of guessing from filenames | - -**Unverified platform detail:** Meta's sharing best-practice page returned HTTP 429 during this review; legacy X/Twitter large-card documentation redirected to the developer overview rather than the old specification. No current X-specific dimensional guarantee is inferred from copied third-party charts. The optional 2:1 and square previews are crop stress tests. Recheck official documentation and real previews for a destination-specific task. [Meta page attempted](https://developers.facebook.com/docs/sharing/best-practices/), [X page attempted](https://developer.x.com/en/docs/x-for-websites/cards/overview/summary-card-with-large-image). - -## Decisions and limits - -The initial proposed treatment was warm editorial ink because it fits this site's existing card palette and restrained diagrams, and can express both technical and personal subjects. Research supports maintaining a small visual grammar; it does not select this exact palette. Sizes, internal breathing room, preview test widths, file budgets, and the inherited 82/72 px card inset are house decisions, labelled accordingly. - -The author subsequently compared editorial ink, cut paper, coloured pencil, and matte miniature scenes using the same ZeroClaw lunch subject on both site themes, then selected **B — Cut paper**. That selection now defines editorial cut paper, version 1. The accepted sample is bundled with the skill as its persistent style anchor; new subjects should match its material and palette without copying its vegetables or card layout. - -## First style comparison - -Four 1536 × 1024 samples of the same ZeroClaw lunch scene were generated with the built-in tool after the author explicitly authorised that route. The backend model was not exposed, so these are not labelled verified GPT Image 2 outputs. The samples compare editorial ink, cut paper, coloured pencil, and matte miniatures. A browser-rendered contact sheet shows each unchanged image on the site's light and dark background colours. Sid selected cut paper. Two reference-guided final images now illustrate the ZeroClaw post: a 1536 × 1024 inline scene after the introduction and a separate 1200 × 630 social composition. Their final prompts and export details are recorded in [the post's image notes](blog-images/building-on-zeroclaw.md). The strongest outlines are in the ink candidate; the paper and pencil candidates are softer. This is visual review, not a measured engagement result. - -## Revision from the author's visual feedback - -Sid liked the cut-paper material but found the first pair sparse and monotonous. Version 2 keeps the matte paper, soft edges, and lighting while using fuller narrative scenes, people and hands where meaningful, overlapping layers, more colour, stronger movement, and short relevant labels. A minimum object count or blanket ban on text would work against that direction. The original B sample remains a material reference; a richer production example is bundled separately to prevent later sessions from reverting to the sparse layout. - -The resulting set covers all eight articles dated 2026, including the unpublished Namefi draft. The latest fetched `origin/next` (`db064cb`) adds dependency updates but no further articles relative to the inspected content. Each post now has one purposefully placed inline illustration and a 1200 × 630 social image. Existing screenshots, diagrams, article text, dates, and draft states remain intact. Exact generation prompts, corrections, export sizes, and placement anchors live in `docs/blog-images/.md`. The revised ZeroClaw and image-search social scenes were separately recomposed to protect their framing and labels; the other social files use inspected crops of their article masters. - -The generator added unwanted lettering to two scenes despite a restrictive prompt. Those outputs were edited to remove unsupported protocol labels and invented grocery/schedule details. This reinforces an operational rule: asking for exact text does not replace visual review. Short labels such as `C0 00`, `GN`, `MEANING`, and `DETAILS` are useful when they clarify the article's actual idea; decorative pseudo-documentation is not. - -Fresh browser validation exposed that co-located Markdown production notes were included by the broad dynamic content import and failed Turbopack compilation. Production notes now live in `docs/blog-images/`; the skill records this repository-specific boundary. No new loader or application abstraction was needed. - -## Editorial correction after the full 2026 set - -The author liked the cut-paper finish and richer colour but rejected the abstract MEANING/DETAILS machinery and the habit of converting nearby terminology into signs. The current direction is v3: grounded, complementary scenes with sparing, earned text. This is author feedback and editorial judgment, not a new research finding. [The full visual review](blog-images/visual-review.md) records decisions for all eight articles and the other insertion points considered. - -Seven illustrations and their social covers were revised. The website retrospective now uses a current render of its committed archive HTML inline and keeps its paper artwork for social recognition. Two native diagrams were added where they explain previously unillustrated boundaries: Veera's successful fallback to upstream code and Tranquilo's availability recheck before checkout. The initial query-splitting artwork was replaced by the concrete act of choosing an image for a lesson. diff --git a/docs/blog-images/building-on-zeroclaw.md b/docs/blog-images/building-on-zeroclaw.md deleted file mode 100644 index bffa7bf..0000000 --- a/docs/blog-images/building-on-zeroclaw.md +++ /dev/null @@ -1,42 +0,0 @@ -# Visuals: ZeroClaw lunch - -## Editorial review - -The kitchen and household context support the real problem. The LUNCH tag and ribbon merely narrated the picture, so both were removed. The scene establishes the household; the existing Telegram captures and three diagrams supply the evidence and mechanisms. - -The current direction is **editorial cut paper v3: grounded, complementary scenes**. Preserve the selected B material and richer colour; let actions and objects carry the idea. Text is sparse and earned, never a label quota. - -## Assets and placement - -| File | Dimensions | Bytes | -| ------------------------ | ----------- | ------- | -| `lunch-decision-v2.webp` | 1536 × 1024 | 338,458 | -| `opengraph-image.jpg` | 1200 × 630 | 204,477 | - -Asset directory: `src/content/blog/building-on-zeroclaw/`. Inline files use the existing responsive Next image pipeline. Social images use the existing share-image route and both Open Graph and Twitter metadata. - -Placement: Opening, immediately before “Why ZeroClaw”, after the household coordination setup. - -Alt: A paper kitchen scene with a cook chopping vegetables, a pantry of ingredients, and a family member using a phone at a nearby desk. - -Caption: Messages, pantry photos, and old orders finally add up to lunch. - -## Generation brief - -Built-in image generator, explicitly authorised. GPT Image 2 is the preferred model when selection is exposed; this tool does not verify its backend model. Do not claim these are verified GPT Image 2 outputs. The selected material anchor is `.rulesync/skills/blog-images/assets/cut-paper-reference.png`. All depicted people and screen contents are illustrative. - -Edit this existing cut-paper kitchen illustration. Preserve the people, cooking action, food, pantry, home-office, materials, colour, shadows and composition. Remove the entire foreground tag bearing LUNCH, including its string, and remove the broad cream ribbon stretched across the front of the counter. Reveal the natural teal cabinet/counter beneath them. Keep the small food photo lying naturally by the vegetables and the unlettered receipt by the grocery bag. The food and cook already communicate the subject; there must be no title, word or label anywhere. Do not replace the tag with a blank sign. Keep the rich scene intact and 3:2 landscape. - -Final master: `exec-52172c0d-ca19-40b9-8833-1ed901926222.png`. Edit target: `exec-78bd295f-22df-43dd-80c4-f0e4a87b226e.png`. PNG masters remain in the generator output directory. The final delivery assets are stored in the article directory, so rendering does not depend on machine-local generation paths. - -Social recomposition prompt: - -Recompose this finished cut-paper illustration as a wide social cover, aspect ratio1200:630. Preserve the exact scene, people, gestures, objects, warm paper material, rich colour and soft shallow shadows. Rearrange rather than crop so every person's complete head and the central cook's hands, chopping board and meal remain comfortably inside the canvas, with at least10% vertical edge room. Fill the wider room naturally with existing environment; do not add a new conceptual prop. No readable text, labels, badges, signs or title. Keep the central action recognisable in a square central crop. Full artwork only; no frame or blank bands. - -Social master: `exec-d0158959-5689-4483-ab26-a895cdea5800.png`. - -Inline: sRGB WebP quality 88. Social: sRGB JPEG quality 90 with MozJPEG. Sharp performs delivery sizing and encoding only; the built-in generator performs creative edits. - -## Validation - -The article keeps its original prose, metadata and draft status. The current images passed browser checks at 320, 390, 768 and 1440 px in light and dark themes. Social validation confirmed that served JPEG bytes match each saved file. The existing image, social-card and SEO tests pass (3 tests, 17 assertions). Production notes stay outside the dynamically imported article tree. diff --git a/docs/blog-images/building-veera-browser.md b/docs/blog-images/building-veera-browser.md deleted file mode 100644 index c69c3b3..0000000 --- a/docs/blog-images/building-veera-browser.md +++ /dev/null @@ -1,44 +0,0 @@ -# Visuals: Veera browser - -## Editorial review - -The lifting gesture fits subtraction, but circuitry and a spanner implied hardware repair. These were replaced with browser pages and source-document layers; the GN tag was removed. An editable diagram now explains how a successful build can contain a different implementation. - -The current direction is **editorial cut paper v3: grounded, complementary scenes**. Preserve the selected B material and richer colour; let actions and objects carry the idea. Text is sparse and earned, never a label quota. - -## Assets and placement - -| File | Dimensions | Bytes | -| ----------------------- | ----------- | ------- | -| `browser-teardown.webp` | 1536 × 1024 | 355,590 | -| `opengraph-image.jpg` | 1200 × 630 | 190,507 | - -Asset directory: `src/content/blog/building-veera-browser/`. Inline files use the existing responsive Next image pipeline. Social images use the existing share-image route and both Open Graph and Twitter metadata. - -Placement: Brave offered a great deal that would have been wasteful to reproduce: Chromium integration, selected privacy infrastructure, and years of decisions about carrying a browser downstream. It also arrived as a product with assumptions of its own. Before we invested in Veera's product surface, I needed to know whether a small team could separate those assumptions from the platform beneath them and understand what remained. - -Alt: Paper hands lift browser interface panels to reveal layered pages and source documents beneath. - -Caption: Taking features out exposed the paths that assembled the browser. - -## Generation brief - -Built-in image generator, explicitly authorised. GPT Image 2 is the preferred model when selection is exposed; this tool does not verify its backend model. Do not claim these are verified GPT Image 2 outputs. The selected material anchor is `.rulesync/skills/blog-images/assets/cut-paper-reference.png`. All depicted people and screen contents are illustrative. - -Revise this cut-paper illustration about removing features from a software browser. Preserve the central hands lifting the coral browser interface layer, the teal/coral/saffron palette, paper material and rich overlapping composition. Remove the GN luggage tag entirely, the spanner, and the decorative gear. Replace the electronic circuit-board-like components beneath the lifted page with layered flat paper browser pages and folded source-document sheets, visibly containing unlettered indented horizontal paper strips. They should read as software and document layers, not a phone being repaired. Keep the upper browser toolbar and the tray of removed interface panels at left. The workbench is dismantling browser software. No hardware chips, connectors, technical signage, readable text, logos or invented code. Maintain 3:2 framing and the choosing/lifting action in the central crop. - -Final master: `exec-f68b7db2-fbbe-441d-9fe3-0115d9197ad1.png`. Edit target: `exec-ef32c83a-213b-43c0-ade0-88073baf7225.png`. PNG masters remain in the generator output directory. The final delivery assets are stored in the article directory, so rendering does not depend on machine-local generation paths. - -The social JPEG is a centred wide crop of the revised master. Inspect the focal subject, not just dimensions. - -Inline: sRGB WebP quality 88. Social: sRGB JPEG quality 90 with MozJPEG. Sharp performs delivery sizing and encoding only; the built-in generator performs creative edits. - -## Additional explanatory figure - -A native Mermaid diagram follows the source-redirection explanation in “The green build I didn’t trust”. It compares an override-present path through Brave with an override-removed path through Chromium; both can reach a successful build. Accessible title and description preserve the distinction. - -## Validation - -The article keeps its original prose, metadata and draft status. The current images passed browser checks at 320, 390, 768 and 1440 px in light and dark themes. Social validation confirmed that served JPEG bytes match each saved file. The existing image, social-card and SEO tests pass (3 tests, 17 assertions). Production notes stay outside the dynamically imported article tree. - -The added diagram renders at 320, 390 and 1440 px in both themes, with readable labels and no internal horizontal scrolling. Its local Mermaid spacing and wrapped labels preserve natural font size. diff --git a/docs/blog-images/facebook-messenger-protocol-stack.md b/docs/blog-images/facebook-messenger-protocol-stack.md deleted file mode 100644 index 25bc2d0..0000000 --- a/docs/blog-images/facebook-messenger-protocol-stack.md +++ /dev/null @@ -1,38 +0,0 @@ -# Visuals: Messenger protocol - -## Editorial review - -The reversed packet is specific and useful, and C0 00 earns its lettering because those exact bytes are the discovery. The opened envelope suggested contents in an empty keepalive; it was removed, along with the sewing spool and generic tabs. The notebook and network cable now stay subordinate to the direction. - -The current direction is **editorial cut paper v3: grounded, complementary scenes**. Preserve the selected B material and richer colour; let actions and objects carry the idea. Text is sparse and earned, never a label quota. - -## Assets and placement - -| File | Dimensions | Bytes | -| ----------------------- | ----------- | ------- | -| `backwards-packet.webp` | 1536 × 1024 | 214,048 | -| `opengraph-image.jpg` | 1200 × 630 | 153,107 | - -Asset directory: `src/content/blog/facebook-messenger-protocol-stack/`. Inline files use the existing responsive Next image pipeline. Social images use the existing share-image route and both Open Graph and Twitter metadata. - -Placement: That looks laughably small after an evening spent doubting the transport. It also set the method for everything that followed: start with the public standard, keep what matches, and put each private variation behind a narrow seam. - -Alt: A coral packet marked C0 00 travels from a server toward a client computer, above an engineer's notebook and network cable. - -Caption: The useful clue was a keepalive travelling the wrong way. - -## Generation brief - -Built-in image generator, explicitly authorised. GPT Image 2 is the preferred model when selection is exposed; this tool does not verify its backend model. Do not claim these are verified GPT Image 2 outputs. The selected material anchor is `.rulesync/skills/blog-images/assets/cut-paper-reference.png`. All depicted people and screen contents are illustrative. - -Edit this cut-paper network illustration. Keep the client computer at left, server at right, the single large cream ribbon arrow from server to client, and the coral closed packet bearing the exact text C0 00. That real diagnostic byte token is the only text. Remove the open envelope and all of its nested contents from the foreground: this particular packet has no payload, and the contents are misleading. Remove the sewing spool of wire and the loose coloured tabs. In that foreground put an ordinary open unlettered engineer's notebook and a pencil, with a loosely coiled network cable at the side; keep these modest and subordinate to the packet's reverse direction. Keep the existing rich paper material, colours, books, shadows and overall3:2 composition. Do not fill the space with another machine, abstraction or extra labels. - -Final master: `exec-d0650880-9067-40c4-b063-4a44469405c5.png`. Edit target: `exec-6a13beab-5ea0-4f3b-ab3a-c10779d177b6.png`. PNG masters remain in the generator output directory. The final delivery assets are stored in the article directory, so rendering does not depend on machine-local generation paths. - -The social JPEG is a centred wide crop of the revised master. Inspect the focal subject, not just dimensions. - -Inline: sRGB WebP quality 88. Social: sRGB JPEG quality 90 with MozJPEG. Sharp performs delivery sizing and encoding only; the built-in generator performs creative edits. - -## Validation - -The article keeps its original prose, metadata and draft status. The current images passed browser checks at 320, 390, 768 and 1440 px in light and dark themes. Social validation confirmed that served JPEG bytes match each saved file. The existing image, social-card and SEO tests pass (3 tests, 17 assertions). Production notes stay outside the dynamically imported article tree. diff --git a/docs/blog-images/from-jsonb-filters-to-self-querying-media-search.md b/docs/blog-images/from-jsonb-filters-to-self-querying-media-search.md deleted file mode 100644 index 06be8bd..0000000 --- a/docs/blog-images/from-jsonb-filters-to-self-querying-media-search.md +++ /dev/null @@ -1,40 +0,0 @@ -# Visuals: Image search - -## Editorial review - -The MEANING/DETAILS lens-and-stencil machine required the reader to decode an invented system and repeated the nearby query-splitting diagram. It was replaced completely with an editor comparing forearm and lower-leg teaching illustrations against a lesson. No labels are needed. The paper anatomical pictures are illustrative, not clinical evidence or actual catalogue assets. - -The current direction is **editorial cut paper v3: grounded, complementary scenes**. Preserve the selected B material and richer colour; let actions and objects carry the idea. Text is sparse and earned, never a label quota. - -## Assets and placement - -| File | Dimensions | Bytes | -| -------------------------------- | ----------- | ------- | -| `choosing-a-teaching-image.webp` | 1536 × 1024 | 252,424 | -| `opengraph-image.jpg` | 1200 × 630 | 146,265 | - -Asset directory: `src/content/blog/from-jsonb-filters-to-self-querying-media-search/`. Inline files use the existing responsive Next image pipeline. Social images use the existing share-image route and both Open Graph and Twitter metadata. - -Placement: In September 2024, I explored this through two TypeScript prototypes. One started with the structured content we already had. The other put a language model in front of media retrieval. The useful bit was where they met. - -Alt: An editor compares a forearm illustration with the matching picture in a lesson, while setting aside a lower-leg image. - -Caption: An image of the right subject can still be the wrong choice for a lesson. - -## Generation brief - -Built-in image generator, explicitly authorised. GPT Image 2 is the preferred model when selection is exposed; this tool does not verify its backend model. Do not claim these are verified GPT Image 2 outputs. The selected material anchor is `.rulesync/skills/blog-images/assets/cut-paper-reference.png`. All depicted people and screen contents are illustrative. - -Create a NEW illustration using the attached image ONLY for matte layered cut-paper material, soft edges, fibre texture, warm ivory, shallow shadows. Rich teal, coral and saffron, natural overlapping shapes. Editorial art for a personal engineering story about an educational-content editor finding the right image for a question. -Depict a close, tangible moment of choosing teaching material: an editor's hands at a desk, one hand holding a small printed illustration of a forearm next to an open lesson page containing a matching forearm illustration and space for prose, the other setting aside a card showing a lower leg. A few overlapping alternative forearm cards, a coloured pencil, a paperclip and a small reference book create the everyday context. The matching card should be the largest, clearest object near centre. Show the anatomical outlines as simple benign educational drawings built from layered paper, no skin conditions, diagnoses or clinical photographs. A modest monitor in the back can show a contact sheet of the same kind of body-location thumbnails with no readable interface details. The editor is comparing assets for a lesson; do not make it look like a craft machine or fantasy processing factory. -The scene should convey 'this one fits the question' through the hand gesture and corresponding pictures, without abstract labels, arrows, stencils, lenses, checkmarks, floating ribbons or badges. No readable text anywhere. No claim to be an actual product screenshot or medical evidence. Landscape 3:2, target1536x1024. Concentrate the choosing hand, the complete forearm card, and its corresponding lesson picture within the middle vertical band y220–800 and central area, so a wide social crop retains the action. Environment can fill the edges. Only artwork, no frame. - -Final master: `exec-3b803a4c-9ef3-4ca5-a042-0aa5f8f295d7.png`. PNG masters remain in the generator output directory. The final delivery assets are stored in the article directory, so rendering does not depend on machine-local generation paths. - -The social JPEG is a centred wide crop of the revised master. Inspect the focal subject, not just dimensions. - -Inline: sRGB WebP quality 88. Social: sRGB JPEG quality 90 with MozJPEG. Sharp performs delivery sizing and encoding only; the built-in generator performs creative edits. - -## Validation - -The article keeps its original prose, metadata and draft status. The current images passed browser checks at 320, 390, 768 and 1440 px in light and dark themes. Social validation confirmed that served JPEG bytes match each saved file. The existing image, social-card and SEO tests pass (3 tests, 17 assertions). Production notes stay outside the dynamically imported article tree. diff --git a/docs/blog-images/i-took-search-away-from-my-lead-finding-agent.md b/docs/blog-images/i-took-search-away-from-my-lead-finding-agent.md deleted file mode 100644 index 5121fb3..0000000 --- a/docs/blog-images/i-took-search-away-from-my-lead-finding-agent.md +++ /dev/null @@ -1,42 +0,0 @@ -# Visuals: Namefi buyer discovery - -## Editorial review - -The labelled EVIDENCE binder, conveyor, coins, rejection badges and magnifier made the scene a generic process factory. Colleagues now consult shared source material at an ordinary desk. This is an analogy for research stages inheriting context, not a literal team portrait or a measured workflow. The actual benchmark stays in its existing table. - -The current direction is **editorial cut paper v3: grounded, complementary scenes**. Preserve the selected B material and richer colour; let actions and objects carry the idea. Text is sparse and earned, never a label quota. - -## Assets and placement - -| File | Dimensions | Bytes | -| ---------------------- | ----------- | ------- | -| `shared-evidence.webp` | 1536 × 1024 | 373,562 | -| `opengraph-image.jpg` | 1200 × 630 | 209,469 | - -Asset directory: `src/content/blog/i-took-search-away-from-my-lead-finding-agent/`. Inline files use the existing responsive Next image pipeline. Social images use the existing share-image route and both Open Graph and Twitter metadata. - -Placement: There was much less work in the second run, but the judge liked the resulting opportunities more. That was encouraging enough to keep investigating the architecture. It also gave the optimisation a useful direction: preserve what a paid call discovers so the next call can ask a better question. - -Alt: Paper researchers consult one open binder together; one points to an existing source while another adds a page. - -Caption: Each research pass could inherit the evidence instead of buying the same discovery again. - -## Generation brief - -Built-in image generator, explicitly authorised. GPT Image 2 is the preferred model when selection is exposed; this tool does not verify its backend model. Do not claim these are verified GPT Image 2 outputs. The selected material anchor is `.rulesync/skills/blog-images/assets/cut-paper-reference.png`. All depicted people and screen contents are illustrative. - -Rework this cut-paper research-room illustration while preserving its people, rich teal/coral/saffron paper style, shallow shadows and shared-research subject. Make the office feel natural instead of a labelled concept factory. Remove the EVIDENCE tab entirely, the conveyor belt, magnifying glass, all coins, all red rejection badges and the sealed gold-stamped envelope. Replace the conveyor with one ordinary curved shared desk. Place a normal-sized open ring binder at the centre of that desk, with clipped source-page thumbnails and coloured tabs but no charts or numbers. One colleague points to a source already in that binder, another passes a new page, and a third reads the same folder from the other side. Keep a small shelf of unlabelled company research folders to establish the work. No readable lettering, no substitute word-symbols or oversized symbolic machine. Let the connected gestures around the shared material tell the story. 3:2 landscape; hands and shared binder in the central band y220–800. - -Final master: `exec-8bc454af-f467-48c4-bd03-7a4b6e716cae.png`. Edit target: `exec-329921e5-4069-464c-a943-ab500348565b.png`. PNG masters remain in the generator output directory. The final delivery assets are stored in the article directory, so rendering does not depend on machine-local generation paths. - -Social recomposition prompt: - -Recompose this finished cut-paper illustration as a wide social cover, aspect ratio1200:630. Preserve the exact scene, people, gestures, objects, warm paper material, rich colour and soft shallow shadows. Rearrange rather than crop so every person's complete head and the central shared open binder and pointing/passing hands remain comfortably inside the canvas, with at least10% vertical edge room. Fill the wider room naturally with existing environment; do not add a new conceptual prop. No readable text, labels, badges, signs or title. Keep the central action recognisable in a square central crop. Full artwork only; no frame or blank bands. - -Social master: `exec-31dee923-fa65-4e93-af5f-f51ddea3b189.png`. - -Inline: sRGB WebP quality 88. Social: sRGB JPEG quality 90 with MozJPEG. Sharp performs delivery sizing and encoding only; the built-in generator performs creative edits. - -## Validation - -The article keeps its original prose, metadata and draft status. The current images passed browser checks at 320, 390, 768 and 1440 px in light and dark themes. Social validation confirmed that served JPEG bytes match each saved file. The existing image, social-card and SEO tests pass (3 tests, 17 assertions). Production notes stay outside the dynamically imported article tree. diff --git a/docs/blog-images/i-wanted-a-queue-not-a-matchmaker.md b/docs/blog-images/i-wanted-a-queue-not-a-matchmaker.md deleted file mode 100644 index 72f4808..0000000 --- a/docs/blog-images/i-wanted-a-queue-not-a-matchmaker.md +++ /dev/null @@ -1,38 +0,0 @@ -# Visuals: Hinge queue - -## Editorial review - -The spread of fictional profile cards and pencil already convey unhurried choice and editable drafts. The LATER divider contributed no new information and was removed entirely. The existing joining diagram covers how feed and profile context become one card. - -The current direction is **editorial cut paper v3: grounded, complementary scenes**. Preserve the selected B material and richer colour; let actions and objects carry the idea. Text is sparse and earned, never a label quota. - -## Assets and placement - -| File | Dimensions | Bytes | -| ------------------------ | ----------- | ------- | -| `queue-on-my-terms.webp` | 1536 × 1024 | 311,182 | -| `opengraph-image.jpg` | 1200 × 630 | 179,048 | - -Asset directory: `src/content/blog/i-wanted-a-queue-not-a-matchmaker/`. Inline files use the existing responsive Next image pipeline. Social images use the existing share-image route and both Open Graph and Twitter metadata. - -Placement: The first client fetched the recommendation feeds, joined them to profiles and media, and saved the information needed to act later. It gave me the queue I wanted: I could look without making a choice just to move the interface along. - -Alt: A hand spreads five fictional profile cards while another edits a separate conversation draft with a pencil. - -Caption: A queue gave me room to look, leave, and choose later. - -## Generation brief - -Built-in image generator, explicitly authorised. GPT Image 2 is the preferred model when selection is exposed; this tool does not verify its backend model. Do not claim these are verified GPT Image 2 outputs. The selected material anchor is `.rulesync/skills/blog-images/assets/cut-paper-reference.png`. All depicted people and screen contents are illustrative. - -Make a local edit to this finished cut-paper illustration. Remove the entire cream divider labelled LATER behind the rightmost profile card; reveal the normal ivory and teal desk background there. Preserve all five illustrated profile/hobby cards, their different people and activities, the hands, drafting pencil, draft sheet, eraser, envelope, rich plum/coral/teal/sage colours, material and shadows. Do not put a blank sign in place of the divider, and do not replace the word with a badge or icon. No readable text anywhere. The spread of cards and the hand editing a draft already convey browsing and human choice. Keep 3:2. - -Final master: `exec-9a888ce5-0524-4254-95a6-f52013350f3d.png`. Edit target: `exec-bb99f603-c84f-4e87-9dfc-c02f0160dbc3.png`. PNG masters remain in the generator output directory. The final delivery assets are stored in the article directory, so rendering does not depend on machine-local generation paths. - -The social JPEG is a centred wide crop of the revised master. Inspect the focal subject, not just dimensions. - -Inline: sRGB WebP quality 88. Social: sRGB JPEG quality 90 with MozJPEG. Sharp performs delivery sizing and encoding only; the built-in generator performs creative edits. - -## Validation - -The article keeps its original prose, metadata and draft status. The current images passed browser checks at 320, 390, 768 and 1440 px in light and dark themes. Social validation confirmed that served JPEG bytes match each saved file. The existing image, social-card and SEO tests pass (3 tests, 17 assertions). Production notes stay outside the dynamically imported article tree. diff --git a/docs/blog-images/no-slots-so-i-built-tranquilo.md b/docs/blog-images/no-slots-so-i-built-tranquilo.md deleted file mode 100644 index f27afdc..0000000 --- a/docs/blog-images/no-slots-so-i-built-tranquilo.md +++ /dev/null @@ -1,44 +0,0 @@ -# Visuals: Tranquilo - -## Editorial review - -The oversized clock/calendar, Saved Request and AFTER 6 labels repeated the prose; checkmarks could imply booked appointments. The replacement shows the benefit: reading at home while a phone notification waits beside a laptop. A separate native diagram makes the recheck/cart/payment boundary explicit. - -The current direction is **editorial cut paper v3: grounded, complementary scenes**. Preserve the selected B material and richer colour; let actions and objects carry the idea. Text is sparse and earned, never a label quota. - -## Assets and placement - -| File | Dimensions | Bytes | -| ---------------------- | ----------- | ------- | -| `an-evening-back.webp` | 1536 × 1024 | 331,056 | -| `opengraph-image.jpg` | 1200 × 630 | 173,572 | - -Asset directory: `src/content/blog/no-slots-so-i-built-tranquilo/`. Inline files use the existing responsive Next image pipeline. Social images use the existing share-image route and both Open Graph and Twitter metadata. - -Placement: There were two parts to that request. “An hour tomorrow after six” needed interpretation. “Keep looking” needed something that would still remember the request after I'd closed the conversation. The second part turned out to be the more interesting one. - -Alt: A person reads in an armchair while a phone notification sits beside an open laptop on the side table. - -Caption: The watch could keep looking while I got on with my evening. - -## Generation brief - -Built-in image generator, explicitly authorised. GPT Image 2 is the preferred model when selection is exposed; this tool does not verify its backend model. Do not claim these are verified GPT Image 2 outputs. The selected material anchor is `.rulesync/skills/blog-images/assets/cut-paper-reference.png`. All depicted people and screen contents are illustrative. - -Recompose this illustration as a natural domestic evening in the same rich tactile cut-paper style and teal/coral/saffron palette. Keep the relaxed reader in a coral armchair, open book, cup, leafy plant, floor lamp and night window. Remove the giant clock, giant calendar, Saved Request note, AFTER 6 label, all checkmarks, winding path, floating bell and blank card in the reader's hand. The reader now has both hands naturally holding the open book and is absorbed in reading. On a small ordinary side table nearer the centre sits a phone showing just one understated notification-shaped panel, with no text, ticks or confirmation symbols; beside it an open laptop has a very simple unlettered appointments-grid silhouette. The machines sit quietly in the room; no arrows or connecting ribbons. The subject is relief from repeatedly checking an app, not a magical booking machine. Make the phone, book and reader the connected focal group; retain enough detail in the lamp, folds, furniture and window to feel warm and involved. No readable text or numerals anywhere, no reservation/payment imagery. Landscape3:2; complete face, phone and book inside middle vertical band y180–815 for later wide social crop. - -Final master: `exec-d4b44983-fc44-4d2f-9bb8-c30bbcb02496.png`. Edit target: `exec-78dca124-2e96-4fff-9d88-d673db6d32f6.png`. PNG masters remain in the generator output directory. The final delivery assets are stored in the article directory, so rendering does not depend on machine-local generation paths. - -The social JPEG is a centred wide crop of the revised master. Inspect the focal subject, not just dimensions. - -Inline: sRGB WebP quality 88. Social: sRGB JPEG quality 90 with MozJPEG. Sharp performs delivery sizing and encoding only; the built-in generator performs creative edits. - -## Additional explanatory figure - -A native Mermaid diagram follows the paragraph ending “find something, choose it, then pay” in “The slot can still disappear”. It shows notification, human choice, an exact-slot recheck, fresh cart state, the overbooking path, and human payment approval. It complements the earlier scheduler sequence, which ends at notification. - -## Validation - -The article keeps its original prose, metadata and draft status. The current images passed browser checks at 320, 390, 768 and 1440 px in light and dark themes. Social validation confirmed that served JPEG bytes match each saved file. The existing image, social-card and SEO tests pass (3 tests, 17 assertions). Production notes stay outside the dynamically imported article tree. - -The added diagram renders at 320, 390 and 1440 px in both themes, with readable labels and no internal horizontal scrolling. Its local Mermaid spacing and wrapped labels preserve natural font size. diff --git a/docs/blog-images/one-cent-three-ledger-entries.md b/docs/blog-images/one-cent-three-ledger-entries.md deleted file mode 100644 index c42fec7..0000000 --- a/docs/blog-images/one-cent-three-ledger-entries.md +++ /dev/null @@ -1,155 +0,0 @@ -# One Cent, Three Ledger Entries: image notes - -Article: `src/content/blog/one-cent-three-ledger-entries/page.mdx`. - -## Direction - -House treatment: editorial cut paper, version 2. Asset revision: 3, abstract amounts. - -The author approved the rich workshop scenes but found the numerical amounts confusing. Targeted edits replace the amounts with physical metaphors while preserving the composition, people, colour, texture and supporting objects. The opening and social card use a lone shared token; the refund keeps receipts labelled “Paid” and “Returned”; the ledger drives an unnumbered mechanical gauge. The lost-acknowledgement illustration remains unchanged. - -Token counts and the gauge position are conceptual, not a second worked numerical example. Exact amounts belong to the article's prose, table and code. The prose, metadata and Mermaid diagram are unchanged; captions and alt text match the edited artwork. These images are analogies, not screenshots or records of real events. - -## Generation and references - -Route: built-in image generator, backend model unverified. Revisions used the approved version 2 originals as edit targets, inspected before editing. All semantic changes were made through the generator. Export used the installed Sharp dependency. - -The original visual family used `/home/sid/.codex/skills/blog-images/assets/cut-paper-reference.png` for material and lighting and `/home/sid/.codex/skills/blog-images/assets/cut-paper-scene-reference.webp` for richer scene density. Their subjects were excluded. The first selected workshop illustration supplied the reference for subsequent scenes. - -Final assets are beside the article. Originals remain outside the published content tree. These notes live in `docs/blog-images/` so the article importer does not treat them as a runtime module. - -## Exports - -| File | Dimensions | Encoding | Bytes | -| --------------------------- | ----------- | ------------------------- | ------: | -| `competing-requests.webp` | 1536 × 1024 | WebP, quality 82 | 280,616 | -| `charge-and-refund.webp` | 1536 × 1024 | WebP, quality 82 | 256,274 | -| `ledger-projection.webp` | 1536 × 1024 | WebP, quality 82 | 235,592 | -| `lost-acknowledgement.webp` | 1536 × 1024 | WebP, quality 82 | 278,622 | -| `opengraph-image.jpg` | 1200 × 630 | JPEG, quality 88, mozjpeg | 199,878 | - -All exports retain an opaque ivory background. Inline masters are 1536 × 1024. The separately composed social edit is 1731 × 909, exported at 1200 × 630 without stretching. - -## Placements and final prompts - -### competing-requests.webp - -Purpose: Make the opening race tangible with two simultaneous jobs competing for one remaining balance. - -Placement: After the opening paragraph ending “what an error actually told me.” - -Alt: Two couriers bring unmarked job slips to a shared workshop till holding a lone paper token. - -Caption: Both requests reach for the same remaining balance. - -Edited original: `/home/sid/.codex-outlook/generated_images/01a07e86-f16a-7361-9b55-180a20e3b66f/exec-cabdb68b-7376-463d-9e7c-e16e1da3e9b6.png`. - -Edit target: `/home/sid/.codex-outlook/generated_images/01a07e86-f16a-7361-9b55-180a20e3b66f/exec-2e674145-53c0-4fa5-b168-ca5442c0d580.png`. - -Final edit prompt: - -```text -Use case: precise-object-edit. Edit the attached image locally. Preserve the accepted composition, people, gestures, warm ivory paper, saturated teal/coral/saffron palette, layered matte cut-paper texture, lighting, rich workshop setting, film strips and other supporting objects. The author likes the scene but finds its numerical amounts confusing. Replace literal arithmetic with a clear physical metaphor. Do not introduce any digits, currency symbols, equations, numerical scales or new decorative text. Keep all other artwork as close to the original as possible. -Replace both '200' request cards with plain cream folded job slips, with a subtle embossed paper fold and no printing. Replace the central '200 left' sign with a small glass-fronted recess built into the same teal-and-saffron till, holding a SINGLE LARGE plain saffron paper token, visibly the remaining shared resource. It must look like a tangible disc inside a compartment, not an icon on a blank sign. Remove all loose coins from the open drawer so the drawer is empty; the lone unmarked token in the central compartment is the only credit token in this scene. The two arriving couriers still converge on that same counter with their unnumbered job slips. Preserve the dynamic converging paths, rich scenery and original character poses. No lettering anywhere in the edited focal objects. No denominations or symbols on the token. Keep the original landscape aspect ratio. -Target inline composition: 1536 by 1024. -``` - -### charge-and-refund.webp - -Purpose: Show a return creating new evidence while the original payment record stays intact. - -Placement: Replace the original ledger illustration after the reserve-versus-charge paragraph ending “open-ended usage or partial-delivery pricing.” - -Alt: A workshop clerk returns a token after a failed print job while receipts marked Paid and Returned remain together in the ledger. - -Caption: The return gets a new entry. The earlier charge remains in the record. - -Edited original: `/home/sid/.codex-outlook/generated_images/01a07e86-f16a-7361-9b55-180a20e3b66f/exec-21cee819-85c9-4d76-a3bc-48cdb4c8cf34.png`. - -Edit target: `/home/sid/.codex-outlook/generated_images/01a07e86-f16a-7361-9b55-180a20e3b66f/exec-edefd8af-8762-4fb5-bfe2-656f91d77b43.png`. - -Final edit prompt: - -```text -Use case: precise-object-edit. Edit the attached image locally. Preserve the accepted composition, people, gestures, warm ivory paper, saturated teal/coral/saffron palette, layered matte cut-paper texture, lighting, rich workshop setting, film strips and other supporting objects. The author likes the scene but finds its numerical amounts confusing. Replace literal arithmetic with a clear physical metaphor. Do not introduce any digits, currency symbols, equations, numerical scales or new decorative text. Keep all other artwork as close to the original as possible. -Keep the clerk handing the saffron token back to the customer, the curved return ribbon and the open ledger containing BOTH intact receipts. Remove '200' from each receipt. The earlier left receipt should read exactly 'Paid' and the newly added right receipt exactly 'Returned', centred and cleanly printed with generous paper around the words. These are the only focal labels, with no amounts or units. Preserve the attached old receipt, the failed print job and all physical action. Avoid substituting symbols or diagrams for the receipts. Target 1536 by 1024. -``` - -### ledger-projection.webp - -Purpose: Show a balance as a consequence of the ledger rather than an independently edited number. - -Placement: In “Let the ledger own the balance”, after “A correction goes through a new entry.” - -Alt: A receipt enters a paper ledger whose gears and belt drive a protected, unnumbered balance gauge. - -Caption: The ledger drives the balance. The gauge has no independent write path. - -Edited original: `/home/sid/.codex-outlook/generated_images/01a07e86-f16a-7361-9b55-180a20e3b66f/exec-b50eb019-3954-4a66-bfe2-81515cdadae8.png`. - -Edit target: `/home/sid/.codex-outlook/generated_images/01a07e86-f16a-7361-9b55-180a20e3b66f/exec-a63a7bd9-4233-4843-ac8e-9a3e63d50028.png`. - -Final edit prompt: - -```text -Use case: precise-object-edit. Edit the attached image locally. Preserve the accepted composition, people, gestures, warm ivory paper, saturated teal/coral/saffron palette, layered matte cut-paper texture, lighting, rich workshop setting, film strips and other supporting objects. The author likes the scene but finds its numerical amounts confusing. Replace literal arithmetic with a clear physical metaphor. Do not introduce any digits, currency symbols, equations, numerical scales or new decorative text. Keep all other artwork as close to the original as possible. -Replace the '200' card being fed into the ledger with an unprinted cream receipt with a folded corner. Replace the entire numeric '800 credits' counter face with a cream SEMICIRCULAR ANALOG DIAL: a simple teal-and-saffron arc and one dark pointer, without numbers, tick marks, units, percentages, letters or labels. The dial is an abstract balance indicator, not a data chart. Keep the dial behind the same protective translucent cover and visibly connected to the ledger through the existing saffron gears and belt. Preserve the ledger pages, receipts, inspector and magnifying glass. Do not add an independent handle or control to the gauge. Target 1536 by 1024. -``` - -### lost-acknowledgement.webp - -Purpose: Separate completed durable work from an acknowledgement that failed to reach its recipient. - -Placement: In “A timeout doesn't tell me whether the money moved”, after “If I blindly repeat the top-up, I can deliver them twice.” - -Alt: A purchase receipt marked Recorded remains safely filed while its acknowledgement envelope tears in transit, leaving the recipient with no reply. - -Caption: The credits can be recorded even when the acknowledgement never arrives. - -Retained original: `/home/sid/.codex-outlook/generated_images/01a07e86-f16a-7361-9b55-180a20e3b66f/exec-f94e6d8d-76ec-434b-ac2f-cd4ee84d35f3.png`. - -Generation inputs: the selected version 2 competing-requests original and the material reference. The submitted prompt below retains an inert leading assembly token. - -Final generation prompt: - -```text -undefined -Image 1 is the selected illustration from this article: preserve its paper character, people treatment, palette and richness, but create the new scene below. Image 2 supplies the original paper material and lighting only; do not copy its subject. -Create a lively cut-paper postal-workshop scene about a completion acknowledgement being lost after the real work is already recorded. Left half: a teal-clad worker has already placed a large cream purchase receipt and saffron credit tokens safely in an open but solid archive drawer. The receipt bears the single large legible word 'RECORDED', a stamp physically printed on the paper. The drawer contains orderly older records and feels settled. Centre: the worker's lightweight coral acknowledgement envelope is flying out through a window, where a gust bends its paper trail and tears the envelope into a few large pieces. Right half: a second person at a small coral desk waits with an empty in-tray and a modest paper clock; a short desk note reads exactly 'No reply'. Their reaching gesture follows the interrupted delivery path back toward the left. Keep the recorded receipt and credits untouched and clearly present while the message is lost. Build overlapping planes, folded curtains, paper floor strips, layered drawers and the dramatic curling message path; every object supports either durable storage, message travel, or waiting. Use the same teal, coral, saffron, warm cream and charcoal palette. Landscape 1536 by 1024 with large enough receipt and desk note to read on a phone. No title overlay, no software screenshot, no extra words or digits. This is a visual analogy for a lost acknowledgement, not a literal delivery event. -``` - -### opengraph-image.jpg - -Purpose: Represent the post in a feed with the same competing-request scene and richer palette. - -Placement: Existing Open Graph/Twitter share-image route; no inline placement. - -Alt: Two requests converge on a workshop till holding one shared token. - -Edited original: `/home/sid/.codex-outlook/generated_images/01a07e86-f16a-7361-9b55-180a20e3b66f/exec-a0026fa5-69cb-4283-8052-b531ed6e1351.png`. - -Edit target: `/home/sid/.codex-outlook/generated_images/01a07e86-f16a-7361-9b55-180a20e3b66f/exec-55c3387e-f1ad-4bf7-b13d-701721f373b5.png`. - -Final edit prompt: - -```text -Use case: precise-object-edit. Edit the attached image locally. Preserve the accepted composition, people, gestures, warm ivory paper, saturated teal/coral/saffron palette, layered matte cut-paper texture, lighting, rich workshop setting, film strips and other supporting objects. The author likes the scene but finds its numerical amounts confusing. Replace literal arithmetic with a clear physical metaphor. Do not introduce any digits, currency symbols, equations, numerical scales or new decorative text. Keep all other artwork as close to the original as possible. -Replace both '200' request cards with plain cream folded job slips, with a subtle embossed paper fold and no printing. Replace the central '200 left' sign with a small glass-fronted recess built into the same teal-and-saffron till, holding a SINGLE LARGE plain saffron paper token, visibly the remaining shared resource. It must look like a tangible disc inside a compartment, not an icon on a blank sign. Remove all loose coins from the open drawer so the drawer is empty; the lone unmarked token in the central compartment is the only credit token in this scene. The two arriving couriers still converge on that same counter with their unnumbered job slips. Preserve the dynamic converging paths, rich scenery and original character poses. No lettering anywhere in the edited focal objects. No denominations or symbols on the token. Keep the original landscape aspect ratio. -Preserve the existing wide social composition, targeting a 1.905:1 landscape image around 1731 by 909. Keep the shared token compartment and both approaching job slips clustered centrally so the action remains recognisable in a small central-square thumbnail. No title overlay. -``` - -## Review - -The revised local draft passed browser checks at 320, 390, 768 and 1440 CSS pixels in light and dark themes. All four images decoded, the Mermaid diagram rendered, and there was no page overflow or browser runtime error. Visually inspected the set at equal sizes, mobile figures, desktop dark rendering and social previews. No numerical amounts remain in the artwork or its figure descriptions. - -The actual Open Graph and Twitter metadata use the same share-image URL. Its local response matched the exported JPEG byte for byte: 1200 × 630, 199,878 bytes. Reviewed 600 × 315 and 360 × 189 previews plus a central square thumbnail; the shared token and both approaching slips remain visible. - -At the checked 1080-pixel optimized size, image responses were 107,092 bytes for competing requests, 106,084 for the refund, 97,865 for the projection and 105,089 for the retained acknowledgement. Responsive mobile delivery uses the existing image pipeline. - -A before/after comparison confirmed every character outside the figures, including article prose and metadata, was preserved. Formatting passed. The post remains a local draft. The earlier article build, TypeScript and blog Markdown checks predate this image revision; the current revision was verified on the development server and has not been published. - -Artifacts: - -- `/home/sid/.codex-outlook/visualizations/2026/09/08/01a07e86-f16a-7361-9b55-180a20e3b66f/ledger-v3-browser-results.json` -- `/home/sid/.codex-outlook/visualizations/2026/09/08/01a07e86-f16a-7361-9b55-180a20e3b66f/ledger-v3-final-verification.json` -- `/home/sid/.codex-outlook/visualizations/2026/09/08/01a07e86-f16a-7361-9b55-180a20e3b66f/ledger-v3-four-scenes.png` diff --git a/docs/blog-images/the-website-that-waited-2776-days.md b/docs/blog-images/the-website-that-waited-2776-days.md deleted file mode 100644 index 3e5e39d..0000000 --- a/docs/blog-images/the-website-that-waited-2776-days.md +++ /dev/null @@ -1,32 +0,0 @@ -# Visuals: Website revival - -## Editorial review - -The paper doorway and calendar sweep work as a social recognition image, but do not substantiate the detailed description of the old website. Inline artwork was replaced by a real local render of the committed archived HTML and moved beside that description. The existing paper social cover was retained; its dates identify the actual eras. - -The current direction is **editorial cut paper v3: grounded, complementary scenes**. Preserve the selected B material and richer colour; let actions and objects carry the idea. Text is sparse and earned, never a label quota. - -## Assets and placement - -| File | Dimensions | Bytes | -| ------------------------ | ----------- | ------- | -| `archived-homepage.webp` | 1536 × 1024 | 213,840 | -| `opengraph-image.jpg` | 1200 × 630 | 213,317 | - -Asset directory: `src/content/blog/the-website-that-waited-2776-days/`. Inline files use the existing responsive Next image pipeline. Social images use the existing share-image route and both Open Graph and Twitter metadata. - -Placement: The introduction crossed out Los Angeles, New Delhi, and Mumbai before arriving in Berlin. I worked at Lufthansa and was passionate about lambda calculus, house music, and Mexican food. Then came the heartbeat. The page said I had been lifelogging since 2014 and promised fresh RescueTime activity and Last.fm plays beneath a tiny **“Crunching latest data...”** animation. That promise had not aged brilliantly. - -Alt: The archived YUPPI.ES homepage: pink masthead, cyan links, crossed-out former cities, Berlin and Lufthansa in the introduction, and a loading message for lifelogging feeds. - -Caption: The archived homepage, rendered from the HTML preserved on master. - -## Capture and social source - -The screenshot renders `index.html` from archived `origin/master` commit `0dd47f41a0073b5e9b60f0b2b4596824c3f8bd58`, with its embedded styling. Chrome viewport: 900 × 950 CSS px, device scale 2. JavaScript was disabled to preserve the committed server-rendered content without running obsolete integrations. The top 1800 × 1200 pixels were captured and exported as lossless WebP at 1536 × 1024. This is a current render of historical HTML, not a screenshot claimed to have been taken in 2018. The loading message is the stored initial state. - -The paper artwork `website-revival.webp` is retained as a social-art source. Its wide JPEG remains unchanged: an old dark website beside a writing desk, with dates 2018 and 2026. It is a conceptual companion, not a reproduction of either site. Generated master: `exec-677a88dc-b52e-436c-a5f7-9671fe20fce2.png`. - -## Validation - -The article keeps its original prose, metadata and draft status. The current images passed browser checks at 320, 390, 768 and 1440 px in light and dark themes. Social validation confirmed that served JPEG bytes match each saved file. The existing image, social-card and SEO tests pass (3 tests, 17 assertions). Production notes stay outside the dynamically imported article tree. diff --git a/docs/blog-images/visual-review.md b/docs/blog-images/visual-review.md deleted file mode 100644 index 161e436..0000000 --- a/docs/blog-images/visual-review.md +++ /dev/null @@ -1,39 +0,0 @@ -# Review of the 2026 article visuals - -The first set had the right material treatment but too often turned the article's nouns into labelled objects. Richness should come from gesture, setting, colour and relationships. A picture should add a recognisable scene or clarify a specific relationship without requiring the reader to decode another abstract system. - -## Decisions across all eight articles - -| Article | Critique | Implemented decision | -| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| ZeroClaw lunch | The kitchen is recognisable and relevant. The LUNCH tag and message ribbon explain what the scene already shows. | Kept the cook, food, pantry and household context; removed the tag and ribbon. Updated inline and wide social art. | -| Messenger protocol | The reversed packet makes the anomaly memorable. An opened envelope of contents is misleading next to a zero-payload keepalive. | Removed the open envelope and unrelated props. Kept `C0 00`: these exact bytes matter, unlike a decorative topic label. Updated inline and social art. | -| Website revival | The doorway/calendar collage evokes a return, but cannot support the precise description of the old page. | Kept the paper artwork for social use. Replaced it inline with an actual render of archived HTML, next to the description of the old introduction and loading feeds. | -| Veera browser | Lifting layers fits subtraction; chips and a spanner make it look like phone repair. GN on a tag is forced terminology. | Replaced the circuitry with browser pages and source documents; removed the tools and tag. Added a precise diagram at the silent-fallback passage. | -| Image search | MEANING/DETAILS, the lens and the stencil form a contraption the article never needed. The nearby Mermaid already explains the query split. | Replaced the whole concept with an editor comparing images against a lesson. No labels. Updated its social cover too. | -| Namefi buyer discovery | The conveyor, labelled binder, coins, badges and magnifier turn the story into a generic business-process poster. | Replaced them with colleagues consulting the same source material at a shared desk. The metaphor is continuity of research; the benchmark table remains the evidence. | -| Hinge queue | The spread of profiles and hand editing a draft already convey room to choose and human control. | Kept those gestures and the distinct fictional activities. Removed the LATER divider, including the sign itself. Updated social art. | -| Tranquilo | The giant scheduling machinery repeats the request. Repeated ticks can suggest confirmed bookings, which the watch does not make. | Replaced it with a reader enjoying an evening while a notification waits nearby. Added a separate diagram for choosing, rechecking and preparing checkout. Updated social art. | - -## Other insertion points reviewed - -| Article and location | What a visual could add | Decision | -| ------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| ZeroClaw: pantry observations and meal completion | Distinguish uncertain pantry evidence from a settled meal decision. | Existing real Telegram captures and three diagrams already cover the interactions and state. More scene art would duplicate them. | -| Messenger: “MQTT outside, MQTToT inside” | A precise nested wire-format figure could clarify framing versus encoded content. | A possible technical close-up if that section is expanded. Keep the current code and layer explanation; no second envelope metaphor. | -| Website: “The frame I reopened” | Let readers see the actual pink masthead, cyan links, obsolete introduction and initial feed state. | Implemented the archive capture immediately after the paragraph ending “That promise had not aged brilliantly.” It replaces the less useful inline metaphor. | -| Veera: “The green build I didn't trust” | Show that two different implementations can both compile. | Implemented a small editable diagram after the paragraph describing source redirection. This is a different question from the existing build-assembly diagram. | -| Image search: “Five neighbours can be one choice” | Show repeated variants beside a genuinely varied set of relevant choices. | A strong future comparison using actual prototype candidates, if available. No captured candidate set was supplied; invented results could overstate an MMR experiment that was never wired into the self-query route. A clearly schematic comparison is an alternative, not a missing required asset. | -| Namefi: benchmark and retry sections | Show costs from the measured run, or the boundary between reusing a result and paying for it again. | The current tables and promotion diagram are sufficient. A retry timeline would earn its place if a concrete failure trace is added; do not invent a trace or a general success rate from one benchmark. | -| Hinge: joining feed entries to profiles | Make the context attached to each card visible. | Already covered by the joining diagram; the opening illustration supplies the experience of browsing. No extra decorative fan of cards. | -| Tranquilo: “The slot can still disappear” | Make clear that a notification is not a reservation and payment remains a separate choice. | Implemented the second diagram after the paragraph ending “find something, choose it, then pay.” The earlier scheduler sequence stops at notification. | - -## Recurring direction - -The skill now carries this as editorial cut paper v3. Use text very sparingly, without a label quota. Preserve exact lettering only when its identity contributes to the story. Removing a word should usually mean removing its unnecessary sign, not substituting a blank sign, badge or floating icon. Mechanism diagrams keep the precise labels they need; scene art does not have to explain every step. - -Keep the chosen paper material and lively colour consistent across posts. Let the subject and composition vary. Ordinary environmental detail is welcome without turning every object into a symbol. Review meaning, placement and potentially misleading implications before polish. - -## Validation - -All eight article images passed 64 viewport/theme checks, including served image resources, alt text, captions and social metadata. The image-search caption received a further eight checks after its final wording change. The two added diagrams passed 12 checks at 320, 390 and 1440 px in both themes, including absence of internal horizontal scrolling. The existing image, social-card and SEO tests passed: 3 tests, 17 assertions. Original article prose and metadata match HEAD after removing the added figures. diff --git a/docs/blog-writing-landscape.md b/docs/blog-writing-landscape.md deleted file mode 100644 index 7761265..0000000 --- a/docs/blog-writing-landscape.md +++ /dev/null @@ -1,104 +0,0 @@ -# AI-assisted personal blogging: landscape and decisions - -Researched September 7, 2026, for Sid Jain's blog. The useful pattern is to give an assistant the author's observations, language and unfinished thinking, then use it to shape the story and finish the publishing work. A voice guide needs examples and corrections. The publishing workflow needs to cover what appears when someone reads, searches for, or shares the article. - -This review follows firsthand accounts to their published work and, where available, their public prompts and implementations. It distinguishes a writer's reported experience from measured audience growth. Most available accounts support claims about time saved or sustained publishing; they do not establish that AI caused better writing or more traffic. Repository stars were not used as a quality score. Source files were inspected without installing or executing the researched workflows. - -## People with useful, inspectable workflows - -| Practitioner | What they actually report or show | Recipe worth taking | -| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Katie Parrott, Every** | Describes delivering eight articles, three ebooks and a larger set of social/email assets in about two weeks with AI. This is a self-reported client workload. Every also publishes examples and a public writing toolkit. | Put interviews, writing examples and editorial preferences into durable context; separate developing the idea, drafting and editing; capture recurring corrections. Her [account](https://every.to/working-overtime/ai-turned-me-into-a-content-agency-of-one) is partially paywalled. The [style-guide resource](https://every.to/guides/ai-style-guide) and [toolkit](https://github.com/EveryInc/compound-writing) provide accessible mechanics. Every sells subscriptions and writing tools, so this is also a vendor account. | -| **Pedro Pinto, developer/designer** | Shows his own working route from rough notes to a published Eleventy site. The article describes a sustainable routine, without a numeric productivity claim. | Capture ideas by voice, expand a rough draft in Obsidian, leave small research instructions inline, then ask ChatGPT or opencode to polish with a personal skill. Read the finished article all the way through. Use a PR deployment preview to check the actual page. [Workflow](https://pedropinto.me/blog/my-blogging-workflow-from-idea-to-production/). | -| **Alexander Makarov** | Reports reducing travel-post preparation from three–four hours to about one hour. His account includes published travel writing and an explanation of the old and new workflow. | Record the experience while it is fresh, transcribe it, clean up speech, then transform the result into Hugo Markdown and metadata. He discovered that built-in phone transcription removed the need for his cloud transcription pipeline. Photo selection remains a distinct job. [Workflow](https://makarovalex.com/post/blog-automation/). | -| **Dom Kirby** | Describes a repeatable process used on his own technical blog; says it makes publishing faster and more frequent, without comparative measurements. | Draft in Google Docs with Gemini assistance, use a fresh ChatGPT conversation for another reading, and generate title/slug/description material after the article is finished. He uses Gemini imagery and Canva for more directed graphics, then adapts the finished article for distribution. [Workflow](https://domkirby.com/blog/ai-assisted-blog-writing-workflow/). | -| **Alexander Opalic, alexop.dev** | Publishes technical articles, shares a blogging system-prompt approach, demonstrates AI-generated Mermaid, and releases screenshot and article-generation skills. This is a visible publishing practice, not a demonstrated traffic uplift. | Give the assistant concrete format and voice instructions. Explain the mechanism before asking for its diagram. Capture actual application screens with annotations, and inspect the final visual. [LLM workflow](https://alexop.dev/posts/how-i-use-llms/), [diagram workflow](https://alexop.dev/posts/how-to-use-ai-for-effective-diagram-creation-a-guide-to-chatgpt-and-mermaid/), [screenshot workflow](https://alexop.dev/posts/app-screenshots-claude-code-skill/). | -| **Max Woolf** | Used GPT-3 to explore titles for a technical post, published the notebooks, and reported the resulting post received over 200 Hacker News points. That single result does not isolate the title's contribution. | Generate several honest title alternatives and choose with editorial judgment. His classifier also preferred misleading candidates, which he rejected. The historical model and fine-tuning code are not a current stack recommendation. [Experiment and outcome](https://minimaxir.com/2022/08/gpt3-blog-title-optimizer/), [notebooks](https://github.com/minimaxir/gpt3-blog-title-optimizer). | -| **Simon Willison** | Explicitly says that first-person opinions on his blog are his own writing, while he uses LLMs for proofreading. | Treat proofreading as a useful workflow in its own right. Do not count a prolific AI developer as evidence of successful AI ghostwriting. His boundary is stricter than Sid's requested collaborative drafting, but protecting the author's actual opinions transfers directly. [Writing policy](https://simonwillison.net/2026/Mar/1/ai-writing/). | - -The strongest fit is a combination: Parrott's maintained voice context, Pinto's rough personal draft, Makarov's voice capture, Kirby's final-draft packaging, and Opalic's visual tooling. These can all happen inside the existing repository workflow. Using different models for every pass is an option, not a demonstrated prerequisite. - -## What the GitHub sources contain - -The links below point to the actual files inspected. Moving branches may change after this review; the most relevant snapshots were Every `18702f0`, Sentry `c2f99a5`, eunomia `e091531`, Humanizer `9862685`, and Opalic's blog generator `7bba090`. - -| Repository / inspected material | Useful part | Decision for this blog | -| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [EveryInc/compound-writing](https://github.com/EveryInc/compound-writing/tree/18702f0ece9f2b852e305807e0271b2d550d9b4b/skills): README, interview, voice-check, reader and tracks skills | Portable author context; separate voice from publication rules; a first-time reader pass that cannot silently fill gaps from research notes. | Incorporate these techniques into one skill. Do not install the full reviewer cast. Its tracks pass can remove discovery narration that Sid explicitly wants, so retain the real sequence of learning. | -| [getsentry/skills](https://github.com/getsentry/skills/blob/c2f99a5b04b4cd992ec3022d7c2c3e23e938d241/skills/blog-writing-guide/SKILL.md): blog-writing-guide | Specific mechanisms, useful code, diagrams, and a consistent voice through the middle of a technical article. | Adopt selective technical depth. Decline mandatory limitations sections, FAQ/definition padding, and an opening formula that would displace a real anecdote. This is a company's editorial standard, not proof that its whole blog is AI-written. | -| [eunomia-bpf/eunomia.dev](https://github.com/eunomia-bpf/eunomia.dev/tree/e091531a375c458ed34c973a5861b75ebf9b3473/.agents/skills): blog-writer, blog-writing-style, seo-geo | A real technical publishing repository with bilingual editorial instructions, bounded revision, and a distinct metadata/distribution layer. | Keep prose review and mechanical checks separate. Do not import its fixed model, paragraph-edit protocol, compulsory keyword placement or claims about AI citation behaviour. | -| [delorenj/skills](https://github.com/delorenj/skills/tree/d8dd7957d588f3d5734ee6af5b5acb7a07c1d8ae/blog-writing): skill and voice reference | Particularly concrete author-specific examples, including how sentence rhythm and humour differ from generic punchy copy. | Learn the method of explaining accepted and rejected sentences. Do not import Jarad's jokes, profanity, persona or signature ending. | -| [doeixd/writing-skill](https://github.com/doeixd/writing-skill/blob/89e200098a5f5e2111a1f3ed43c2668ba5b02798/blog-writing/SKILL.md) | Draft the explanation before polishing the opening; revise relationships and rhythm. | Useful small workflow. Its default personality and punctuation counts do not define Sid's voice. No outcome evidence found in the inspected skill. | -| [blader/humanizer](https://github.com/blader/humanizer/blob/9862685f575c65a8247f90369951df1b3416e3d6/SKILL.md) | Diagnoses structural habits: staged candour, repeated antithesis, dramatic fragments, generic closers and formatting by formula. | Use as an editorial diagnostic, never as an AI-detector score or a source of invented reactions. A deliberately chosen phrase can stay. | -| [haowjy/creative-writing-skills](https://github.com/haowjy/creative-writing-skills/tree/fd7a3ad9cd7697a0645ff6ff4bd5e809cf7673a3/skills/creative-writing-craft/resources): prose-writing and scene-construction | Pace, narrative distance, transitions, and concentrating detail where something changes. | Adapt craft to nonfiction. Fictional scenes, dialogue and inner reactions must not be supplied to make a personal story more vivid. | -| [Adkid-Zephyr/anti-defensive-writing-Skill](https://github.com/Adkid-Zephyr/anti-defensive-writing-Skill/blob/b32067b3055d356e007c6986775fee069da3891a/skills/anti-defensive-writing-en/SKILL.md) | Directly recognises the self-undermining tone Sid dislikes. | Reject as a governing guide: it favours a press-conference posture and suppresses experimental chronology. Sid wants the experience of trying and discovering things. Removing unnecessary defence does not require hiding meaningful failures. | -| [alexanderop/blog-generator](https://github.com/alexanderop/blog-generator/tree/7bba09047de69dde0bcccad0d0e03402531fc289/skills/blog-generator): README and validation script | Treats the rendered article as an artifact; validates links, code labels, diagrams and unresolved placeholders. | Borrow mechanical checking. Reject a required 12–15-section article, diagram quotas and a rebuild-plan ending. Existing MDX already provides its HTML, highlighting and theme features. | -| [alexanderop/app-screenshots](https://github.com/alexanderop/app-screenshots): README | Captures real screens and adds an annotation overlay tied to page elements. | Borrow focused, annotated screenshots. Capture the few screens that explain a discovery, rather than documenting every page. Existing browser automation can do this. | -| [alexanderop/blog-cover-generator](https://github.com/alexanderop/blog-cover-generator/blob/ace4534a13759538c6baa679226e79bfb570275c/components/editor/cover-editor.tsx): editor implementation | A configurable cover editor with title, font, colours, image and logo controls. | Do not recommend it as working AI cover generation: the inspected generation branch is a TODO. This is why inspecting source matters for tool selection. | -| [minimaxir/gpt3-blog-title-optimizer](https://github.com/minimaxir/gpt3-blog-title-optimizer/blob/main/gpt3_title_optimizer_demo.ipynb): demo notebook | Generates title variants and scores them separately. | Keep variant generation and human selection; omit fine-tuning and automated virality scores. | -| [vercel/satori](https://github.com/vercel/satori): README | Produces graphics from a supported subset of HTML/CSS, including typography. | Use through the existing Next.js ImageResponse API for predictable social-card text. No additional renderer dependency. | -| [excalidraw/excalidraw](https://github.com/excalidraw/excalidraw): README | Editable drawings, PNG/SVG export and an open drawing format. | Optional for an illustration that needs manual spatial composition. Mermaid already covers this site's system diagrams. Save the editable source if used. | -| [vercel-labs/agent-browser](https://github.com/vercel-labs/agent-browser): README | Browser navigation, screenshots and element references for agents. | A viable alternative browser interface. Do not add a second browser stack while the existing tooling handles capture and review. | - -## The recipes to put into practice - -**Start with something only the author could supply.** A messy account, a conversation transcript, an observation from the project, a failed attempt, or a strong opinion gives the assistant something to organise. When that material already exists, use it. When one missing anecdote carries the whole opening, ask for that detail rather than making one up. Voice recording is an optional input method; ordinary notes work. - -**Teach voice through decisions.** Keep a few short, authentic examples and explain what works: where the sentence turns, how the joke lands, how much setup the reader needs. Store the user's accepted corrections as a small number of reusable rules. Do not train the next draft's voice exclusively on previous machine-generated drafts; that compounds the very habits being removed. - -**Separate revision jobs.** First repair the story: what changed, why the next attempt followed, and where the interesting discovery is buried. Then repair the sentences. Finally read the article as a reader who has never seen the repository. That last pass should identify exact places where curiosity becomes confusion or the explanation starts to drag. It should not demand a defence of every statement. Stop when the substantive issues are fixed instead of running endless adversarial reviews. - -**Finish the title and packaging from the finished article.** An early title can guide the piece, but the final title, summary and social card should describe the story that survived revision. Generate a small set of alternatives when needed, then select for specificity and an honest promise. Metadata is allowed to mention the searchable technology even when the literary title takes a different angle. - -**Give each visual a job.** A screenshot shows what a real interface did. A sequence diagram makes timing visible. A flowchart explains a decision. A conceptual illustration sets a scene or explains an analogy. A social card helps someone recognise and choose the article in a feed. One asset can serve multiple jobs only if the crop and readability work. - -The complementary prose references remain [Julia Evans on blogging myths](https://jvns.ca/blog/2023/06/05/some-blogging-myths/), [her programming-comic process](https://jvns.ca/blog/2020/12/05/how-i-write-useful-programming-comics/), and [Paul Graham on revision](https://paulgraham.com/writing44.html). They support selective explanation, rewarding small discoveries and conversational prose; they are craft references, not AI-success case studies. - -## The complete publishing package - -| Part | What the workflow produces and checks | Tool choice here | -| --------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Article | Personal narrative, interesting code, genuine outcome, useful references | One writing skill and the current agent; source browsing and GitHub access | -| Metadata | Specific title, standalone summary, author, original publication date, meaningful tags and an honest updated date when appropriate | Existing MDX metadata export and schema | -| Inline visuals | Relevant screens or illustrations, captions, alt text, sensible crop, readable detail in light/dark mode | Existing local-image pipeline; browser capture; available image generation for conceptual art | -| Diagrams | One legible relationship per figure, accurate arrows, accessible title/description, editable source | Existing Mermaid support; optional SVG/Excalidraw for a spatial illustration | -| Social previews | An image for every article, useful title at feed size, crop-safe margins, fetchable image URL and correct card tags | Existing Next.js image routes plus the shared title-card fallback added in this change | -| Embeds | Repository where the project enters the story; relevant PR/pinned code beside its explanation; source links that survive embed failure | Existing GitHub embed transform. Commit-page and tweet embeds remain unsupported; use a direct link or attributed excerpt, adding native support when an actual post needs it | -| Discovery | Canonical URL, article structured data, index entry, RSS, sitemap and Markdown export | Existing site infrastructure; inspect actual deployed output | -| Release | Rendered mobile/desktop article, functioning media and links, passing build/checks, published route and live social image | Existing PR/Vercel workflow and browser QA | -| Distribution | A short, channel-appropriate introduction that still sounds like the author | Draft from the finished article when requested; social/email sending needs explicit authorisation | - -At the audit's start, the site already had MDX, Shiki, Mermaid, local image imports, GitHub cards, schema-validated metadata, canonical tags, BlogPosting JSON-LD, RSS, a sitemap, Markdown exports, and Vercel previews. Only two of eleven real articles had co-located social images. The implemented fallback gives the other nine a title card without requiring hand-authored files per article. Existing custom artwork still takes precedence. The Kitchen Sink is a rendering fixture and remains a draft. - -For conceptual art, use a compact visual brief: the idea to communicate, the scene or analogy, palette, composition, intended crop and what needs empty space. Generate the illustration separately from the typography; compose exact title text with the site's renderer. Review the result at article size and feed size. Keep screenshots and measured charts as real captures or data-driven graphics, never generated stand-ins. Opalic's [theme-aware diagram article](https://alexop.dev/posts/excalidraw-dark-mode-astro-diagrams/) is a useful reminder that an image has to survive the site's theme as well as the editor preview. - -Search advice needs its own filter. Google says descriptions have no fixed length limit and may be truncated for the available display width; a concise useful sentence is a better rule than a mandatory character count. It also says AI Overviews and AI Mode need no special AI text file or schema. Keep the existing machine-readable exports because they are useful, without promising a ranking boost. [Google's snippet guidance](https://developers.google.com/search/docs/appearance/snippet), [AI-search guidance](https://developers.google.com/search/docs/appearance/ai-features). - -## What we should use - -Use the current agent, repository context, browser/GitHub research, the new writing skill, Mermaid, screenshots, available image generation and the site's native metadata/OG pipeline. That covers this blog's current needs. [Next.js ImageResponse](https://nextjs.org/docs/app/api-reference/functions/image-response) supplies social-image rendering without a new service. - -Every's Compound Writing is the most relevant larger toolkit to revisit if writing becomes a separate multi-project operation. Excalidraw is the most useful optional visual tool when Mermaid cannot express the composition. Voice capture is worthwhile if speaking about a project is easier than writing the raw notes. None needs to become a required installation for the next post. - -Do not add an autonomous content farm, fine-tune a model, purchase an SEO suite, impose a reviewer panel, or install a humanizer merely to make the tool list longer. The strongest immediate improvements are the author's raw material, concrete voice examples, bounded editing, and publication checks that include the assets around the prose. - -The resulting instructions live in the [blog-writing skill](../.rulesync/skills/blog-writing/SKILL.md), with [original reusable prompts](../.rulesync/skills/blog-writing/references/prompts.md) and the site's [publishing guide](../BLOG.md). The prompts are adaptations written for this project, not copied source prompts. - -## Writing craft references - -- [Julia Evans, Some blogging myths](https://jvns.ca/blog/2023/06/05/some-blogging-myths/): personal accounts and small discoveries are enough; choose a reader instead of explaining every prerequisite. Adopted the permission to be specific and selective. Did not adopt habitual uncertainty qualifiers as a substitute for editorial checking. -- [Julia Evans, How I write useful programming comics](https://jvns.ca/blog/2020/12/05/how-i-write-useful-programming-comics/): a familiar technical fact can still be a rewarding surprise to someone learning it. Applied to choosing technical close-ups and diagrams that make one discovery legible. -- [Paul Graham, Writing, Briefly](https://paulgraham.com/writing44.html): conversational language, substantial revision, reading aloud, cutting digressions, and recognising when an essay has reached its ending. Applied as revision practice, not an imitation of his voice. -- [Xamfonos, Technical Writing Best Practices skill](https://github.com/Xamfonos/technical-writing-best-practices/blob/main/SKILL.md): concepts need context, transitions need reasons, and solutions should follow an understood problem. Rejected its requirement to visibly substantiate every claim and its compulsory arc: those would recreate the audit-like tone this skill is meant to remove. -- [haowjy, Creative Writing Craft — Prose Writing](https://github.com/haowjy/creative-writing-skills/blob/main/skills/creative-writing-craft/resources/prose-writing.md): vary rhythm and narrative distance; concentrate detail at moments that matter and summarise routine activity. Adapted to nonfiction, where details and inner reactions must come from the author. -- [haowjy, Creative Writing Craft — Scene Construction](https://github.com/haowjy/creative-writing-skills/blob/main/skills/creative-writing-craft/resources/scene-construction.md): enter a scene with something underway, vary pace, and keep transitions oriented. Borrowed movement and pacing, not fictional dialogue or imposed dramatic stakes. - -## Follow-up: consistent AI illustrations and social images - -The September 8 [image-production research](blog-images-research.md) -follows the visual leads above and examines Every's actual article-image practice, -Why Try AI's style experiments, stylegen's source, and other firsthand workflows. -It distinguishes publishing evidence from audience-growth claims and records which -techniques transfer to this site. The resulting [blog-images skill](../.rulesync/skills/blog-images/SKILL.md) -covers finished-post image selection, insertion points, a maintained house style, -reference-guided generation, deterministic typography, and inspected social crops. diff --git a/docs/site-seo-landscape.md b/docs/site-seo-landscape.md deleted file mode 100644 index 5765e34..0000000 --- a/docs/site-seo-landscape.md +++ /dev/null @@ -1,105 +0,0 @@ -# SEO and agent publishing research - -Reviewed September 7, 2026. The reusable deliverable is the -[site-seo skill](../.rulesync/skills/site-seo/SKILL.md), paired with -[blog-writing](../.rulesync/skills/blog-writing/SKILL.md). This note is a map to -the research and implementation, not an additional workflow agents must load. - -The research covered official Google, Bing, OpenAI, Anthropic, IndexNow, -Open Graph, llms.txt and Lighthouse documentation; a GEO research paper; -firsthand browser-agent SEO accounts; and twelve GitHub implementations. -The earlier [writing landscape](blog-writing-landscape.md) covers the writing, -story, media and production research. - -## What to emulate - -Agent-driven SEO works best as a short feedback loop: inspect the real page and -provider data, change the shared source, verify the deployment, then measure -what happened. Several repositories make useful parts of that loop concrete: -metadata snapshots in AgriciDaniel's suite, JSON extraction plus judgement in -JeffLi1993's audit, question-to-page mapping in itsbeaudean's skill, and actual -Search Console tools in the GSC MCP projects. The -[source-by-source comparison](#github-implementations) -records exactly what was inspected and which ideas were retained. - -The strongest firsthand SEO example found was -[Alexander Opalic's browser-agent audit](https://alexop.dev/posts/how-i-use-claude-code-for-doing-seo-audits/): -it found development crawl/index settings on a real blog starter and produced -specific source fixes. That is an observable workflow result. It is not a -controlled demonstration that AI-generated articles or an audit increased -organic traffic. The researched tool repositories likewise provide practical -interfaces, not independently established ranking gains. - -## What changes the implementation - -Search crawling, model training and user-requested fetching need separate -decisions. Popular skills in the sample get that distinction wrong. The -[crawler matrix](../.rulesync/skills/site-seo/references/publishing.md) uses -provider documentation and preserves the site's existing policy. - -`llms.txt` is useful navigation for an agent, with standard link relations for -discovering the guide and Markdown pages. It is not a special Google ranking -file. The skill explains the current proposal and gives a task that tests -whether an agent can actually find and explain the author's work. - -Search measurement has changed recently. Google's dedicated generative-AI -impression views were announced in June 2026 and reported as fully rolled out -on August 31; Bing offers an AI Performance preview. The -[measurement recipe](../.rulesync/skills/site-seo/references/measurement.md) -distinguishes those observations from human referral traffic and repeatable -manual citation samples, and includes authenticated API request bodies. - -There is no need to replace the site's native publishing stack. Next.js -metadata routes, JSON-LD, RSS, Mermaid, Markdown exports and the shared social -renderer cover production. Browser and HTTP checks cover public validation. TypeScript tests in the -existing CI cover canonical URLs, preview indexing controls, Markdown exports -and social-image generation. Search Console/Bing account access is the next -capability needed for actual indexing and performance measurement; it is not -required to make and validate the code improvements. - -## Applied to this website - -- Stable production canonical and entity URLs, including when built as a preview. -- Explicit preview `noindex` in metadata and HTTP headers. -- Article Markdown alternate links and `llms.txt` discovery links. -- Visible authorship and substantive revision dates alongside existing publication dates. -- Sitemap focused on intended search destinations, with real modification dates. -- Simpler robots rules that retain the existing allow-all policy. -- Corrected documentation of the full profile context versus individual article exports. -- Reusable SEO guidance, publishing checks, task prompts and measurement recipes. - -The writing changes revise the seven 2026 articles. Shared publishing support -supplies working social previews. All skill instructions protect the author's -personal narrative from keyword quotas, boilerplate FAQs and defensive prose. - -Public-response checks record HTTP/HTML observations. A live page and a valid sitemap do -not establish that Google has indexed it or that an answer engine will cite -it. Those outcomes should be checked with the account-backed recipe after -publication, using the actual release date and a consistent comparison window. - -## GitHub implementations - -| Source inspected | Useful practice carried into this skill | What was rejected or needs verification | -| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills/tree/5b2c0007766c6a1cf1d53fd8fc73e979e0821022/skills), `seo-audit` and `ai-seo` | Start with site context; prioritise indexability; separate technical checks from content judgement. | The inspected AI skill misidentifies crawler roles and says no dedicated Google AI reporting exists. Its 40–60-word answer quotas and claimed citation multipliers are not publishing rules. | -| [AgriciDaniel/claude-seo](https://github.com/AgriciDaniel/claude-seo/tree/a1480c7e590b16001bd9dc1627eacdcd44d580f9), `seo-flow`, `seo-drift`, `seo-google` | Select relevant tasks; snapshot metadata before/after; use actual GSC and field data; distinguish API capabilities. | No need for its full suite, agent hierarchy or SQLite history for this site. Verify newly announced analytics features at the provider. | -| [JeffLi1993/seo-audit-skill](https://github.com/JeffLi1993/seo-audit-skill/tree/523bdfb2c94f4689408a5a344f4ea74ced49ff32), full audit skill and social checker | Deterministic extraction returns JSON; an agent reviews meaning and implements corrections. Fetch real OG/Twitter fields. | Fixed length heuristics are not ranking requirements. A raw HTML parser needs a browser complement, not a claim to see client-rendered data. | -| [itsbeaudean/agent-skills](https://github.com/itsbeaudean/agent-skills/tree/24e0be4faa8221a8cf5dd71cb5b53bea88ed5f48/skills/ai-search-website-audit) | Check whether a real reader question has a clear public answer; convert findings into exact changes and acceptance checks. | Its buyer-oriented framework needs adaptation to a personal technical blog. Do not impose pricing, disclaimers or sales copy on a story. | -| [Bhanunamikaze/Agentic-SEO-Skill](https://github.com/Bhanunamikaze/Agentic-SEO-Skill/tree/69199160e18372bc5cdf9ddec20ccb9fb1b509f1), llms checker and indexability workflow | Inspect different access controls and parse the actual file rather than assuming it exists. | Its weighted llms score and failure framing for an optional missing file are arbitrary. No adopted numerical readiness score. | -| [seoskillsai/seo-skills-ai](https://github.com/seoskillsai/seo-skills-ai/tree/7daed7f36e2d3a74fe864854014e6a432d23e0f6), `seo-robots-ai` | A crawler matrix is a useful format for agent decisions. | The inspected matrix conflates GPTBot with search and Google-Extended with AI Overviews. Use official provider roles instead. | -| [conorbronsdon/gsc-mcp](https://github.com/conorbronsdon/gsc-mcp/tree/92dd3ef651b2abb31373850830f43aa37369790f), README and entry point | Concrete agent tools for performance, URL inspection and sitemap work; small responses; useful missing-credential messages. Author says it was built for a podcast and personal site. | README's full-scope requirement for URL inspection is stricter than Google's API. Tool operation is not evidence of a ranking lift; demo uses sample data. | -| [samalyxx/gsc-seo-mcp](https://github.com/samalyxx/gsc-seo-mcp), README | Practical property/auth setup and prompts for page/query comparisons; distinguishes Indexing API's special-purpose scope. | Setup instructions and claimed features were inspected, not a live authenticated installation. Do not auto-install or copy secrets into a project. | -| [AnswerDotAI/llms-txt](https://github.com/AnswerDotAI/llms-txt/tree/f5aed2aeab1df0ea11e49909a3af86739a09d9a3), proposal and `llms_txt/core.py` | Compact guide with links; progressive retrieval of detail; existing parser/context-building examples. | No need to import its Python dependencies just to generate this site's small Markdown guide. Proposal adoption does not establish search ranking benefit. | -| [GoogleChrome/lighthouse](https://github.com/GoogleChrome/lighthouse/blob/74d982bd211c5fb12c4b2c18c4a1fc8bc17f6b6c/core/audits/agentic/llms-txt.js) | Verified the actual optional-file check: client errors are N/A, server/fetch errors fail; content checks are simple. | Audit wording about crawling/training is not a replacement for provider policy. A passing audit does not demonstrate engine citation. | -| [ahrefs/ahrefs-mcp-server](https://github.com/ahrefs/ahrefs-mcp-server/tree/ca0e1e9996739f690287c396a5ad6e92255aec22) | Maintenance review matters before choosing a tool. | The old local server explicitly says it is unmaintained and points to a remote offering. Do not install it as the default current integration. | -| [eunomia-bpf/eunomia.dev](https://github.com/eunomia-bpf/eunomia.dev/tree/e091531), publishing/SEO skills | Real content repository connecting writing and SEO steps; bounded review passes. | Reject rigid keyword/description quotas, mandatory caution inventories and model-specific orchestration. | - -The [blog-writing research](blog-writing-landscape.md) adds fifteen writing/media repositories and first-person production workflows. These SEO sources complement that work rather than replacing it with marketing prose. - -## Firsthand use versus demonstrated results - -[Alexander Opalic's SEO audit account](https://alexop.dev/posts/how-i-use-claude-code-for-doing-seo-audits/) describes using Claude Code with browser automation on NuxtPapier and finding development indexing controls left in place. The useful recipe is to inspect the running page and point fixes at source files. His theatrical role prompt is incidental; the post does not establish traffic growth caused by the audit. His [Astro llms.txt implementation](https://alexop.dev/posts/how-i-added-llms-txt-to-my-astro-blog/) is a concrete publishing example, not measured citation uplift. - -The GSC MCP repositories demonstrate ways agents can access real search data. Repository stars, screenshots of reports, and tool inventories are not success metrics. Prefer accounts that disclose the workflow and an observable outcome, and label self-reported productivity separately from independently measured audience growth. - -The [GEO research paper](https://arxiv.org/abs/2311.09735) reports benchmark improvements, with results varying by domain. This supports testing useful presentation changes under defined conditions. It does not establish a universal percentage gain from adding statistics, quotations or schema to Sid's blog. Never manufacture these elements to imitate a benchmark treatment.