# Publishing on the Forge blog

The Forge blog is the public editorial surface for engineering stories,
product decisions, and measured release lessons. It is intentionally separate
from the documentation and changelog:

- **Blog posts** explain why a capability exists, what changed while building
  it, and what was learned.
- **Documentation and public specifications** define supported behavior,
  limits, configuration, and APIs.
- **Changelog entries** record concise release facts and measurements.

Public routes:

- Blog index: `https://forge.smol.ai/blog`
- RSS feed: `https://forge.smol.ai/blog/feed.xml`
- Post permalink: `https://forge.smol.ai/blog/<slug>`

## Add a post

Every post has two compile-time sources.

1. Add public metadata to `packages/content/src/blog.ts`. The edge-owned catalog
   supplies the web index, article metadata, social cards, and RSS feed.
2. Add the Markdown body under
   `packages/web/src/features/blog/posts/<slug>.md`, then map it in
   `packages/web/src/features/blog/blogCatalog.ts`.

The build fails typechecking if the metadata shape is invalid. The catalog test
also requires unique, newest-first permalinks and non-empty bodies.

Use a stable, descriptive slug. A published permalink is durable; edit the
post in place for corrections rather than reusing or renaming its slug.

## Editorial standard

A Forge field note should:

1. put the bottom line first in a literal **2–8 word primary title**;
2. use the optional `subtitle` for a short opinion, learning, or hook rather
   than hiding the outcome in wordplay;
3. make the `description` name the main technical achievement and its strongest
   production proof before background or process;
4. distinguish production measurements from estimates or targets;
5. explain the system boundary in plain language;
6. include a diagram, illustration, or compact evidence table when it makes the
   mechanism or comparison easier to understand;
7. describe Cloudflare as Forge's infrastructure provider, not a product Forge
   claims to replace;
8. state explicit limits and uncertainty;
9. link to the authoritative public specification; and
10. avoid credentials, private repository data, internal incident identifiers,
   or claims that were not proven on the owning production surface.

The Field Notes layout presents the shared author identity, publication date,
reading time, and article body in one split-pane route. Put the most
decision-relevant proof in the article itself as a compact table, diagram, or
clearly scoped statement, and link to the durable engineering contract from the
body. The catalog test enforces title length, shared author metadata, and
proof-bearing structure, but editorial review still decides whether a title is
genuinely literal and an illustration genuinely clarifies the system.

## Validate before publishing

```bash
npm test --workspace=packages/web
npm test --workspace=@cloudforge/content
npm test --workspace=@cloudforge/edge
npm run build --workspace=packages/web
```

Visually inspect `/blog` and the post permalink at mobile, tablet, desktop, and
ultrawide widths in both light and dark themes. Confirm:

- no horizontal overflow;
- the index and permalink use the same optional-slug route and browser history
  returns cleanly to the index;
- the primary title, optional subtitle, and technical description remain a
  clear hierarchy;
- the article social-card URL in the server-rendered HTML;
- the post appears in `/blog/feed.xml`; and
- navigation distinguishes Blog, Docs, and Changelog.

After deployment, re-open the public permalink, RSS feed, social-card image,
`llms.txt`, and `/health`. A successful build alone is not publication proof.