Skip to content

docs: add 9 blog posts, 4 tutorials, and tutorials section - #260

Open
jflowers wants to merge 7 commits into
mainfrom
opsx/blog-tutorials-batch
Open

docs: add 9 blog posts, 4 tutorials, and tutorials section#260
jflowers wants to merge 7 commits into
mainfrom
opsx/blog-tutorials-batch

Conversation

@jflowers

Copy link
Copy Markdown
Contributor

Summary

Adds a batch of 9 blog posts and 4 tutorials to the Unbound Force website, plus a new Tutorials documentation section. This closes 13 tracked GitHub issues in a single coordinated effort.

Blog posts cover recent releases and capabilities:

  • CI failure classification (/review-pr signal vs noise)
  • AGENTS.md quality (why it determines code quality)
  • Dewey knowledge stores (v3.1.0 file-backed learnings)
  • Dewey slash command UX (/dewey-store zero-code UX)
  • Pluggable LLM providers (Ollama + Vertex AI)
  • Gaze baseline comparison (per-function CRAP regression)
  • Council review action (Divisor Council in GitHub Actions)
  • Prompt hardening (compression resilience)
  • Multi-platform support (uf init --platform)

Tutorials provide step-by-step guides:

  • Setting up Dewey knowledge stores
  • Configuring Dewey embedding/synthesis providers
  • CRAP baseline comparison in CI with Gaze
  • Customizing hero experience with /onboard

Closes #46, #51, #64, #65, #69, #70, #72, #114, #116, #150, #151, #191, #198

How to Test

  1. Run npm run build — should produce 206 pages with no errors
  2. Run npm run dev and verify:
    • Tutorials section appears in sidebar between Reference and Changelog
    • All 4 tutorials render correctly at /docs/tutorials/
    • All 9 blog posts appear in the blog listing
    • Cross-links between blog↔tutorial pairs work bidirectionally
  3. Click through each tutorial's "Further Reading" section to verify links resolve

How to Demo

  1. Navigate to http://localhost:1313/docs/tutorials/ — see the tutorials landing page with links to all 4 guides
  2. Open a blog post with a companion tutorial (e.g., "Dewey Knowledge Stores") — click the "Try It" link to the tutorial
  3. From the tutorial, click "Further Reading" back to the blog post — bidirectional linking works
  4. Check the sidebar — Tutorials sits between Reference and Changelog

Key Files Changed

Config: menus.en.toml — added tutorials nav entry at weight 37

Blog (9 new): agents-md-quality.md, ci-failure-classification.md, council-review-action.md, dewey-knowledge-stores.md, dewey-slash-command-ux.md, gaze-baseline-comparison.md, multi-platform-support.md, pluggable-llm-providers.md, prompt-hardening.md

Tutorials (5 new): _index.md, dewey-knowledge-stores.md, dewey-provider-configuration.md, gaze-crap-baseline-ci.md, onboard-customization.md

OpenSpec artifacts (6 new): proposal, design, specs, tasks for blog-tutorials-batch

Dewey learnings (2 new): retrospective learnings from the implementation session

This PR was generated by /uf.finale (AI-assisted).

@jflowers jflowers self-assigned this Aug 24, 2026
@jflowers jflowers moved this to Ready for Review 👀 in Unbound Force Planning Aug 24, 2026

@yvonnedevlinrh yvonnedevlinrh left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: REQUEST CHANGES (0 CRITICAL, 3 HIGH, 2 MEDIUM, 1 LOW)

What it does: Adds 9 blog posts + 4 tutorials + a new Tutorials nav section; claims to close 13 issues. Build passes (206 pages, npm run build exit 0). Content quality, security, and structure are strong.

Blocking Issues

# Severity Finding
1 HIGH The 4 new tutorials lack slug: frontmatter, so Hugo derives their URLs from titles. This breaks 7 internal links: 3 blog→tutorial links and 4 links in _index.md.
2 HIGH onboard-customization title contains a literal /, producing a mangled URL /docs/tutorials/getting-started-with-/ (empty trailing segment).
3 HIGH Zero-Waste Mandate violation — dead internal links shipping to production. Same root cause as #1.
4 MEDIUM Tutorial count discrepancy: PR title says "5 tutorials", body and implementation say "4" (pinkman tutorial was removed).
5 MEDIUM specs/tutorials.md still lists the removed Pinkman OSS Scout tutorial (#45) and states "5 tutorials / 15 pages" (actual: 4 tutorials / 14 pages). tasks.md correctly strikes the pinkman task, so spec and tasks disagree.
6 LOW gaze crap baseline command in gaze-baseline-comparison.md may differ from the command specified in issue #151 — verify for copy-paste accuracy.

Dead Link Detail

Tutorials render at title-derived URLs, but links point to filename-based slugs:

  • content/blog/gaze-baseline-comparison.md:143/docs/tutorials/gaze-crap-baseline-ci/ (actual: /docs/tutorials/setting-up-crap-baseline-comparison-in-ci/)
  • content/blog/dewey-knowledge-stores.md:169/docs/tutorials/dewey-knowledge-stores/ (actual: /docs/tutorials/setting-up-dewey-knowledge-stores/)
  • content/blog/pluggable-llm-providers.md:151/docs/tutorials/dewey-provider-configuration/ (actual: /docs/tutorials/configuring-dewey-embedding-and-synthesis-providers/)
  • content/docs/tutorials/_index.md:14-17 → all 4 filename-based slugs, all dead

Not Blocking

  • WARN-level "Description too short" messages on auto-generated /tags/* taxonomy pages. Unrelated to this PR; does not affect the verdict.

Root Cause & Fix

A single mechanical omission — tutorials have no slug: frontmatter. The spec's own Tutorial Frontmatter requirement (specs/tutorials.md) also omits slug, which propagated into implementation.

  1. Add slug: matching each filename to the 4 tutorial frontmatter blocks (dewey-knowledge-stores, dewey-provider-configuration, gaze-crap-baseline-ci, onboard-customization), then npm run build and verify the links resolve in public/.
  2. Correct the PR title to "4 tutorials" and sync specs/tutorials.md (remove pinkman #45; change "5 tutorials / 15 pages" → "4 tutorials / 14 pages").
  3. (LOW) Verify the gaze crap baseline command against the gaze repo.

Content quality, security (SHA-pinned Actions, no secrets), and build health are otherwise strong.

jflowers added a commit that referenced this pull request Aug 27, 2026
…racter

Add slug: frontmatter to all 4 tutorials so Hugo generates URLs
matching the filename stems used in internal links. Fix the
onboard-customization title by removing the literal "/" that
caused Hugo to produce a mangled URL path.

Addresses PR #260 review feedback from @yvonnedevlinrh.

Signed-off-by: jflowers <jflowers@users.noreply.github.com>
Assisted-by: claude-opus
jflowers added a commit that referenced this pull request Aug 27, 2026
Remove the Pinkman OSS Scout Tutorial requirement that was
already struck from tasks.md. Update build validation scenario
from "5 tutorials / 15 pages" to "4 tutorials / 14 pages" to
match the actual implementation.

Addresses PR #260 review feedback from @yvonnedevlinrh.

Signed-off-by: jflowers <jflowers@users.noreply.github.com>
Assisted-by: claude-opus
@jflowers

Copy link
Copy Markdown
Contributor Author

Thanks for the thorough review, @yvonnedevlinrh! All findings addressed:

1. Missing slug: frontmatter (HIGH)
Addressed in 9b39345: Added slug: to all 4 tutorials (dewey-knowledge-stores, dewey-provider-configuration, gaze-crap-baseline-ci, onboard-customization). URLs now match the filename-based paths referenced by blog posts and _index.md.

2. Invalid / in onboard-customization title (HIGH)
Addressed in 9b39345: Title changed from "Getting Started with /onboard —..." to "Getting Started with onboard —...". Combined with the slug fix, URL now resolves correctly as onboard-customization/.

3. Zero-Waste Mandate — dead internal links (HIGH)
Addressed in 9b39345: Same root cause as #1/#2. Verified clean build produces correct URLs and all 7 internal links (3 blog→tutorial + 4 in _index.md) now resolve.

4. PR title "5 tutorials" → "4 tutorials" (MEDIUM)
PR title updated to "docs: add 9 blog posts, 4 tutorials, and tutorials section".

5. Spec still references removed Pinkman tutorial (MEDIUM)
Addressed in 457857f: Removed the Pinkman OSS Scout Tutorial requirement from specs/tutorials.md and corrected counts from "5 tutorials / 15 pages" to "4 tutorials / 14 pages".

6. gaze crap baseline command accuracy (LOW)
Verified against gaze source code (cmd/gaze/main.go): --format=json is valid (lines 915-916), > .gaze/baseline.json matches the documented baseline workflow in gaze's README. Commands in the blog are accurate.

Blog posts covering:
- CI failure classification (#64)
- AGENTS.md quality auditing (#65)
- Dewey knowledge stores (#69)
- Dewey slash command UX (#72)
- Pluggable LLM providers (#116)
- Gaze baseline comparison (#150)
- Council review action (#191)
- Prompt hardening (#198)
- Multi-platform support (#51)

Tutorials covering:
- Dewey knowledge stores (#70)
- Dewey provider configuration (#114)
- Gaze CRAP baseline CI (#151)
- Pinkman OSS Scout (#45)
- Onboard customization (#46)

Adds Tutorials section to navigation menu.
…s-refs, align schemas

- Remove pinkman-oss-scout.md tutorial per user direction
- Fix dead cross-references in dewey-knowledge-stores blog (correct slugs)
- Fix dead link in dewey-knowledge-stores tutorial (/docs/projects/dewey/)
- SHA-pin GitHub Actions in gaze-baseline-comparison blog
- Add missing code block language IDs (FT-001) across 5 files
- Fix Constitution Principle III name (Observable Quality, not Actionable Output)
- Align pluggable-llm-providers blog with tutorial (vertexai, claude model, config path)
- Add blog↔tutorial cross-links in both directions
- Align knowledge stores YAML schema between blog and tutorial
- Standardize gaze CLI flag to --format=json
- Fix MCP tool call syntax labels in dewey-knowledge-stores tutorial
- Add explicit tutorial list to _index.md
- Add Further Reading sections to all tutorials
- Update ci-failure-classification CTA with specific link
Assisted-by: claude-opus
Generated with AI assistance (claude-opus)
…racter

Add slug: frontmatter to all 4 tutorials so Hugo generates URLs
matching the filename stems used in internal links. Fix the
onboard-customization title by removing the literal "/" that
caused Hugo to produce a mangled URL path.

Addresses PR #260 review feedback from @yvonnedevlinrh.

Signed-off-by: jflowers <jflowers@users.noreply.github.com>
Assisted-by: claude-opus
Remove the Pinkman OSS Scout Tutorial requirement that was
already struck from tasks.md. Update build validation scenario
from "5 tutorials / 15 pages" to "4 tutorials / 14 pages" to
match the actual implementation.

Addresses PR #260 review feedback from @yvonnedevlinrh.

Signed-off-by: jflowers <jflowers@users.noreply.github.com>
Assisted-by: claude-opus
@jflowers
jflowers force-pushed the opsx/blog-tutorials-batch branch from 457857f to 37e79bd Compare August 27, 2026 21:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Ready for Review 👀

Development

Successfully merging this pull request may close these issues.

tutorial: Getting started with /onboard — customizing your hero experience

3 participants