W4: Chapters + Patterns + Start + cutover from mkdocs#10
Conversation
…loop, eval-loop, etc.)
📝 WalkthroughWalkthroughAdds a complete Astro-based book site: 14 new MDX chapter pages, pattern pages, layouts, navigation components, dynamic routes and index pages; integrates sitemap support; and changes CI workflows to enable auto-deploy on pushes to master/main while removing the older deploy workflow. ChangesSite content, layouts, routing, and components
Build, integrations, and CI
Estimated code review effort🎯 4 (Complex) | ⏱️ ~50 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
.github/workflows/astro-deploy.yml (2)
13-15:⚠️ Potential issue | 🟠 Major | ⚡ Quick winSet
cancel-in-progress: trueto prevent deployment race conditions.With
cancel-in-progress: false, rapid successive pushes tomasterormainwill trigger concurrent deployments, potentially causing nondeterministic final state or resource conflicts. For deployment workflows, it's safer to cancel in-progress runs so the latest commit always wins.🔄 Proposed fix
concurrency: group: "pages" - cancel-in-progress: false + cancel-in-progress: true🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/astro-deploy.yml around lines 13 - 15, Change the concurrency setting so in-progress deployments are cancelled: update the concurrency block's cancel-in-progress value from false to true (the concurrency config and the cancel-in-progress property in the workflow) so only the latest run for the "pages" group proceeds and previous runs are aborted.
32-34:⚠️ Potential issue | 🟠 Major | ⚡ Quick winAdd lint, typecheck, and test steps before build.
The workflow deploys directly after
pnpm buildwithout running validation steps. The PR description mentions "11/11 tests passing; 0 type errors, 0 warnings," and the AI summary notes that the deleteddeploy.ymlpreviously included lint/typecheck/test jobs. Omitting these checks risks deploying broken code to production.🧪 Proposed fix to add validation steps
- run: pnpm install --frozen-lockfile + - run: pnpm lint + + - run: pnpm typecheck + + - run: pnpm test + - run: pnpm build🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/astro-deploy.yml around lines 32 - 34, The workflow currently runs install and pnpm build only; add explicit validation steps before the build by inserting run steps for lint, typecheck, and tests (e.g., run: pnpm lint, run: pnpm typecheck, run: pnpm test) prior to the existing pnpm build step so the job fails fast on lint/type/test regressions; ensure these steps use the same node version/setup as the install step and reference the same workspace if using pnpm workspaces.
🧹 Nitpick comments (2)
src/components/universal/ChapterMap.astro (1)
12-33: 🏗️ Heavy liftConsider deriving the chapter structure from collection metadata.
The hardcoded
partsarray creates a maintenance burden—if chapters are added, removed, or reorganized in thechapterscollection, this navigation must be manually kept in sync. Consider deriving this structure from chapter frontmatter (e.g., apartfield) to maintain a single source of truth.Potential approach
Instead of hardcoding, you could:
- Add a
partOrderor similar field to chapter frontmatter- Query all chapters via
getCollection('chapters')in the parent layout- Pass the grouped structure as a prop to
ChapterMapThis would eliminate drift between content and navigation structure.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/components/universal/ChapterMap.astro` around lines 12 - 33, The hardcoded parts array in ChapterMap should be replaced by deriving the structure from chapter collection metadata: add a frontmatter field like part and optional partOrder/chapOrder to each chapter, call getCollection('chapters') in the parent layout (or a loader) to fetch all chapters, group them by the frontmatter part value and sort groups by partOrder and items by chapOrder/title, then pass the resulting grouped structure as a prop (e.g., parts or chapterMap) into the ChapterMap component instead of the static parts constant so navigation reflects the single source of truth.src/pages/patterns/index.astro (1)
30-33: ⚡ Quick winConsider improving semantic structure for pattern cards.
While the current link structure is functional and accessible, wrapping each card in an
<article>element or using a heading tag for the pattern name would improve the semantic structure and document outline.🎯 Proposed semantic markup improvement
- <a class="pat-card" href={`/agentic-ai/patterns/${e.data.slug}/`}> - <div class="pat-card__name">{e.data.name}</div> - <p class="pat-card__one-line">{e.data.oneLine}</p> - </a> + <article> + <a class="pat-card" href={`/agentic-ai/patterns/${e.data.slug}/`}> + <h3 class="pat-card__name">{e.data.name}</h3> + <p class="pat-card__one-line">{e.data.oneLine}</p> + </a> + </article>Then adjust the CSS to reset the heading margin:
.pat-card__name { font-family: var(--font-display); font-size: var(--display-3); font-weight: 500; line-height: var(--lh-snug); + margin: 0; }🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/pages/patterns/index.astro` around lines 30 - 33, Wrap each pattern card in an <article> to improve semantics and change the pattern title element inside the card from the div with class "pat-card__name" to a heading (e.g., h3) so the document outline is preserved; update the anchor structure inside the new <article> so the <a class="pat-card"> remains the interactive element linking to `/agentic-ai/patterns/${e.data.slug}/`. Also adjust the stylesheet to reset default heading margins for the pattern card title (target the "pat-card__name" class or the new heading selector) so layout doesn't shift.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/content/chapters/01-what-agentic-means.mdx`:
- Line 158: Update the roadmap paragraph (the sentence starting "In Chapter 2,
we build the components...") so chapter references match the book structure:
keep Chapter 2 as building components, Chapter 3 as deterministic workflow vs
bounded agent, Chapter 4 as evaluation plus tracing/reliability/security
hardening, and Chapter 5 as stepping back to ask whether the task needed an
agent; adjust the chapter numbers in that single sentence accordingly.
In `@src/content/chapters/03-workflow-first-agent-second.mdx`:
- Line 15: Update the user-facing bullet text to hyphenate the compound
adjective: change the phrase "LLM-driven decision making" in the bullet that
starts with "The bounded agent" to "LLM-driven decision-making" so the compound
modifier is consistent and readable.
In `@src/content/chapters/07-when-not-to-use-agents.mdx`:
- Line 36: The Amazon link "[Get the book on
Amazon](https://www.amazon.com/dp/B0GVG6848F)" in the chapter currently returns
HTTP 503; verify the URL responds successfully and replace it if it's
dead—either update the href to a working Amazon product URL or remove/replace
the link with an alternate retailer or a non-link reference; ensure the markdown
anchor text "[Get the book on Amazon]" is preserved or updated to match the new
URL or vendor.
In `@src/content/chapters/12-memory-management.mdx`:
- Line 23: Update the broken companion-link text "src/ch12/" in the line that
reads "The working code for this chapter is in [`src/ch12/`](...)" to point to
the correct directory name "src/ch12_memory/"; replace the displayed path and
the URL fragment so the markdown reads "The working code for this chapter is in
[`src/ch12_memory/`](...)" ensuring the link target matches the actual repo
folder used elsewhere (e.g., memory-agent.mdx).
In `@src/layouts/ChapterLayout.astro`:
- Line 35: The call uses an unsafe assertion "as any" on allEntries when calling
entriesToContentEntries; update entriesToContentEntries (in
~/lib/content-helpers, the entriesToContentEntries function) to accept the
proper union type of your collection entries (or add a type guard/helper that
narrows allEntries to the correct union) so you can call
buildReverseIndex(entriesToContentEntries(allEntries)) without casting; adjust
the function signature and exports accordingly and remove the "as any" at the
call site.
In `@src/layouts/PatternLayout.astro`:
- Around line 31-33: The reverse-link lookup is using d.slug, which can miss
backlinks; change the getReverseLinks call to use the bare entry id instead
(e.g., replace getReverseLinks(reverseIndex, d.slug) with
getReverseLinks(reverseIndex, d.id)), and if your content shape stores the id
elsewhere extract the canonical entry id (from the object used by
buildReverseIndex/entriesToContentEntries) before calling getReverseLinks so the
lookup keys match the reverseIndex.
---
Outside diff comments:
In @.github/workflows/astro-deploy.yml:
- Around line 13-15: Change the concurrency setting so in-progress deployments
are cancelled: update the concurrency block's cancel-in-progress value from
false to true (the concurrency config and the cancel-in-progress property in the
workflow) so only the latest run for the "pages" group proceeds and previous
runs are aborted.
- Around line 32-34: The workflow currently runs install and pnpm build only;
add explicit validation steps before the build by inserting run steps for lint,
typecheck, and tests (e.g., run: pnpm lint, run: pnpm typecheck, run: pnpm test)
prior to the existing pnpm build step so the job fails fast on lint/type/test
regressions; ensure these steps use the same node version/setup as the install
step and reference the same workspace if using pnpm workspaces.
---
Nitpick comments:
In `@src/components/universal/ChapterMap.astro`:
- Around line 12-33: The hardcoded parts array in ChapterMap should be replaced
by deriving the structure from chapter collection metadata: add a frontmatter
field like part and optional partOrder/chapOrder to each chapter, call
getCollection('chapters') in the parent layout (or a loader) to fetch all
chapters, group them by the frontmatter part value and sort groups by partOrder
and items by chapOrder/title, then pass the resulting grouped structure as a
prop (e.g., parts or chapterMap) into the ChapterMap component instead of the
static parts constant so navigation reflects the single source of truth.
In `@src/pages/patterns/index.astro`:
- Around line 30-33: Wrap each pattern card in an <article> to improve semantics
and change the pattern title element inside the card from the div with class
"pat-card__name" to a heading (e.g., h3) so the document outline is preserved;
update the anchor structure inside the new <article> so the <a class="pat-card">
remains the interactive element linking to
`/agentic-ai/patterns/${e.data.slug}/`. Also adjust the stylesheet to reset
default heading margins for the pattern card title (target the "pat-card__name"
class or the new heading selector) so layout doesn't shift.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 97ca9156-559e-4dff-a37d-973a658de05f
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (45)
.github/workflows/astro-deploy.yml.github/workflows/deploy.ymlREADME.mdastro.config.mjspackage.jsonsrc/components/universal/ChapterMap.astrosrc/components/universal/NextPrev.astrosrc/components/universal/ProgressReader.astrosrc/content/chapters/00a-how-llms-work.mdxsrc/content/chapters/00b-api-to-tools.mdxsrc/content/chapters/00c-first-agent.mdxsrc/content/chapters/00d-frameworks.mdxsrc/content/chapters/00e-connecting-to-mcp.mdxsrc/content/chapters/01-what-agentic-means.mdxsrc/content/chapters/02-tools-context-agent-loop.mdxsrc/content/chapters/03-workflow-first-agent-second.mdxsrc/content/chapters/04-multi-agent-without-theater.mdxsrc/content/chapters/05-human-in-the-loop.mdxsrc/content/chapters/06-evaluating-and-hardening.mdxsrc/content/chapters/07-when-not-to-use-agents.mdxsrc/content/chapters/08-metacognition.mdxsrc/content/chapters/09-deployment.mdxsrc/content/chapters/10-governance.mdxsrc/content/chapters/11-security.mdxsrc/content/chapters/12-memory-management.mdxsrc/content/chapters/13-agent-protocols-in-production.mdxsrc/content/patterns/agent-loop.mdxsrc/content/patterns/approval-gate.mdxsrc/content/patterns/cold-start-mitigation.mdxsrc/content/patterns/earn-the-complexity.mdxsrc/content/patterns/escalation-path.mdxsrc/content/patterns/eval-loop.mdxsrc/content/patterns/failure-buckets.mdxsrc/content/patterns/hub-and-spoke.mdxsrc/content/patterns/tool-registry.mdxsrc/content/patterns/trace-the-truth.mdxsrc/content/patterns/verifier-loop.mdxsrc/content/patterns/workflow-first.mdxsrc/layouts/ChapterLayout.astrosrc/layouts/PatternLayout.astrosrc/pages/book/[...slug].astrosrc/pages/book/index.astrosrc/pages/patterns/[...slug].astrosrc/pages/patterns/index.astrosrc/pages/start/index.astro
💤 Files with no reviewable changes (1)
- .github/workflows/deploy.yml
|
|
||
| The complete chapter text is available in the book. | ||
|
|
||
| [Get the book on Amazon](https://www.amazon.com/dp/B0GVG6848F) |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Verify Amazon book link is accessible
curl -I -L -s -o /dev/null -w "%{http_code}" "https://www.amazon.com/dp/B0GVG6848F"Repository: sunilp/agentic-ai
Length of output: 64
The Amazon book link currently returns HTTP 503 (Service Unavailable).
The URL https://www.amazon.com/dp/B0GVG6848F is not currently accessible. Confirm the link is working and returns a successful response before deployment.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/content/chapters/07-when-not-to-use-agents.mdx` at line 36, The Amazon
link "[Get the book on Amazon](https://www.amazon.com/dp/B0GVG6848F)" in the
chapter currently returns HTTP 503; verify the URL responds successfully and
replace it if it's dead—either update the href to a working Amazon product URL
or remove/replace the link with an alternate retailer or a non-link reference;
ensure the markdown anchor text "[Get the book on Amazon]" is preserved or
updated to match the new URL or vendor.
There was a problem hiding this comment.
Pushing back. The Amazon URL https://www.amazon.com/dp/B0GVG6848F is the canonical book product link, used in homepage CTA, SiteFooter, manifesto, R-001, and every chapter since W1. It returns 503 to non-browser User-Agents like curl's default — that's an Amazon anti-bot behavior, not a dead link. Manual browser visit returns 200. The link is correct; updating it across 18+ pages over a non-issue would be churn. Not applying.
There was a problem hiding this comment.
@sunilp, you're absolutely right — Amazon's CDN/bot-protection layer is well-known for returning 503 to automated clients like curl with a default User-Agent, while serving 200 to real browsers. My check produced a false positive. The link is valid and no change is needed. Apologies for the noise.
✏️ Learnings added
Learnt from: sunilp
Repo: sunilp/agentic-ai PR: 10
File: src/content/chapters/07-when-not-to-use-agents.mdx:36-36
Timestamp: 2026-05-13T17:13:31.117Z
Learning: Amazon product URLs (e.g. `https://www.amazon.com/dp/...`) return HTTP 503 to non-browser User-Agents such as `curl` due to Amazon's anti-bot protection. This is NOT indicative of a dead link — a manual browser visit returns 200. Do not flag Amazon links as broken based on curl/automated HTTP checks returning 503 in the sunilp/agentic-ai repository (or in general). Always note this caveat instead of raising a "link broken" review comment for Amazon URLs.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
🧠 Learnings used
Learnt from: sunilp
Repo: sunilp/agentic-ai PR: 9
File: src/layouts/EvidenceLayout.astro:32-33
Timestamp: 2026-05-13T14:36:57.364Z
Learning: In this Astro MDX content-collection setup, cross-reference IDs used in `references` arrays and in `getReverseLinks` lookups must be **bare entry ids** (e.g., `workflow-vs-agent-comparison`), not prefixed with the collection name (e.g., do **not** use `evidence-workflow-vs-agent-comparison`). Frontmatter `id` fields for evidence/lab/project content must stay in sync with the Astro `entry.id` (filename/entry-based). Therefore, layout code should intentionally use `getReverseLinks(reverseIndex, d.id)` (where `d.id` is the bare id) rather than constructing any collection-prefixed id.
| getCollection('patterns'), | ||
| ]); | ||
| const allEntries = [...chapters, ...fieldNotes, ...recipes, ...labs, ...evidence, ...projects, ...patterns]; | ||
| const reverseIndex = buildReverseIndex(entriesToContentEntries(allEntries as any)); |
There was a problem hiding this comment.
Avoid as any type assertion.
The type assertion as any when passing allEntries to entriesToContentEntries bypasses TypeScript's type safety. Consider updating the function signature to accept the union type of all collection entries, or create a proper type guard.
Suggested fix
Update entriesToContentEntries in ~/lib/content-helpers to accept the union of all collection entry types, or create a type-safe helper:
-const reverseIndex = buildReverseIndex(entriesToContentEntries(allEntries as any));
+const reverseIndex = buildReverseIndex(entriesToContentEntries(allEntries));Then update the function signature in content-helpers.ts to handle the union type.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/layouts/ChapterLayout.astro` at line 35, The call uses an unsafe
assertion "as any" on allEntries when calling entriesToContentEntries; update
entriesToContentEntries (in ~/lib/content-helpers, the entriesToContentEntries
function) to accept the proper union type of your collection entries (or add a
type guard/helper that narrows allEntries to the correct union) so you can call
buildReverseIndex(entriesToContentEntries(allEntries)) without casting; adjust
the function signature and exports accordingly and remove the "as any" at the
call site.
There was a problem hiding this comment.
Pushing back. The as any cast is consistent across all 6 layouts (FieldNoteLayout, ProjectLayout, EvidenceLayout, LabReportLayout, ChapterLayout, PatternLayout). The proper fix is to widen the entriesToContentEntries parameter type to accept the Astro union of CollectionEntry types — which means refactoring src/lib/content-helpers.ts and removing 6 cast sites. Worth doing in a focused refactor PR; not worth doing during cutover. YAGNI for now.
There was a problem hiding this comment.
@sunilp, that's a fair call — a cutover PR is not the right place for a cross-cutting type refactor. Noted.
Would you like me to open a follow-up GitHub issue to track the entriesToContentEntries type widening so it doesn't get lost?
✏️ Learnings added
Learnt from: sunilp
Repo: sunilp/agentic-ai PR: 10
File: src/layouts/ChapterLayout.astro:35-35
Timestamp: 2026-05-13T17:13:39.716Z
Learning: In `sunilp/agentic-ai`, the `as any` cast on `allEntries` when calling `entriesToContentEntries(allEntries as any)` in layout files (ChapterLayout.astro, PatternLayout.astro, FieldNoteLayout.astro, ProjectLayout.astro, EvidenceLayout.astro, LabReportLayout.astro) is intentional and consistent across all 6 layouts. The proper fix — widening the `entriesToContentEntries` parameter in `src/lib/content-helpers.ts` to accept the full union of Astro `CollectionEntry` types and removing all 6 cast sites — is deferred to a dedicated refactor PR. Do not flag this `as any` cast in these layout files during reviews until that refactor is done.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
🧠 Learnings used
Learnt from: sunilp
Repo: sunilp/agentic-ai PR: 9
File: src/layouts/EvidenceLayout.astro:32-33
Timestamp: 2026-05-13T14:36:57.364Z
Learning: In this Astro MDX content-collection setup, cross-reference IDs used in `references` arrays and in `getReverseLinks` lookups must be **bare entry ids** (e.g., `workflow-vs-agent-comparison`), not prefixed with the collection name (e.g., do **not** use `evidence-workflow-vs-agent-comparison`). Frontmatter `id` fields for evidence/lab/project content must stay in sync with the Astro `entry.id` (filename/entry-based). Therefore, layout code should intentionally use `getReverseLinks(reverseIndex, d.id)` (where `d.id` is the bare id) rather than constructing any collection-prefixed id.
Learnt from: sunilp
Repo: sunilp/agentic-ai PR: 9
File: src/pages/projects/index.astro:30-30
Timestamp: 2026-05-13T14:37:11.515Z
Learning: In this repository’s Astro site deployed to GitHub Pages, treat hardcoded internal href prefixes that begin with `/agentic-ai/` as intentional (they should match the configured Astro `base`/deployment path). Do not flag these links as an issue during reviews. The team prefers a single repo-wide update if the base path ever changes, rather than replacing link bases with `import.meta.env.BASE_URL` at every link site. Only reconsider if additional deploy targets/base paths are introduced.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/content/chapters/01-what-agentic-means.mdx`:
- Around line 7-14: Remove the invalid cross-reference entry "fn-001" from the
frontmatter references array in the MDX file; locate the YAML frontmatter block
containing the "references:" list (which currently includes 00c-first-agent,
03-workflow-first-agent-second, 04-multi-agent-without-theater, fn-001) and
delete the "fn-001" item (or replace it with a valid reference ID if you have
one) so the references array only contains existing reference IDs.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 75adf2f0-491d-4bb7-aa42-b2d165d63018
📒 Files selected for processing (4)
src/content/chapters/01-what-agentic-means.mdxsrc/content/chapters/03-workflow-first-agent-second.mdxsrc/content/chapters/12-memory-management.mdxsrc/layouts/PatternLayout.astro
✅ Files skipped from review due to trivial changes (1)
- src/content/chapters/12-memory-management.mdx
🚧 Files skipped from review as they are similar to previous changes (2)
- src/content/chapters/03-workflow-first-agent-second.mdx
- src/layouts/PatternLayout.astro
| references: | ||
| - 00c-first-agent | ||
| - 03-workflow-first-agent-second | ||
| - 04-multi-agent-without-theater | ||
| - fn-001 | ||
| patterns: | ||
| - workflow-first | ||
| - agent-loop |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Verify cross-references in frontmatter exist in their collections
echo "=== Checking references array ==="
for id in "00c-first-agent" "03-workflow-first-agent-second" "04-multi-agent-without-theater" "fn-001"; do
echo "Checking: $id"
fd -e mdx -e md "^${id}\\.mdx?\$" src/content/ | head -1
done
echo ""
echo "=== Checking patterns array ==="
for id in "workflow-first" "agent-loop"; do
echo "Checking: $id"
fd -e mdx -e md "^${id}\\.mdx?\$" src/content/ | head -1
done
echo ""
echo "=== Summary ==="
echo "Expected: Each ID should have found a matching file path."
echo "If any ID printed with no file path below it, that cross-reference is broken."Repository: sunilp/agentic-ai
Length of output: 681
Remove the broken cross-reference fn-001 from the references array.
The reference fn-001 on line 9 does not match any entry in the codebase. Remove it or replace it with a valid reference ID.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/content/chapters/01-what-agentic-means.mdx` around lines 7 - 14, Remove
the invalid cross-reference entry "fn-001" from the frontmatter references array
in the MDX file; locate the YAML frontmatter block containing the "references:"
list (which currently includes 00c-first-agent, 03-workflow-first-agent-second,
04-multi-agent-without-theater, fn-001) and delete the "fn-001" item (or replace
it with a valid reference ID if you have one) so the references array only
contains existing reference IDs.
1 participant
⚠ THIS PR PERFORMS THE LIVE CUTOVER FROM MKDOCS TO ASTRO
Two manual user actions are required before/during the merge:
🔴 ACTION 1 — Before merging this PR:
gh-pages) to "GitHub Actions"This switches GitHub Pages to consume the artifact produced by
.github/workflows/astro-deploy.yml(viaactions/deploy-pages) instead of thegh-pagesbranch that mkdocs has been writing to.If this is NOT done before merge, the new workflow will run successfully but GitHub Pages will continue serving the old
gh-pagesbranch content. The site will not actually flip.🟡 ACTION 2 — After merge + successful deploy:
Submit the new sitemap to Google Search Console:
sunilprakash.compropertyhttps://sunilprakash.com/agentic-ai/sitemap-index.xmlRollback plan
If the cutover breaks the live site, revert in two steps:
gh-pages. mkdocs gh-pages branch is unchanged from before this PR.The site will then serve the old mkdocs build from
gh-pagesagain. The W4 work stays preserved on theastro-redesign-w4branch for re-attempt.Summary
Week 4 of the 4-week mkdocs → Astro 5 migration. Builds on W1 (#7), W2 (#8), W3 (#9). This PR:
docs/book/to MDX with proper frontmatter, Callouts, and image path updates. 1700+ lines of substantive content.draftin frontmatter.whenToUse,whenNotToUse, optionalantiPatterncallout./start/audience routing page with 3 tracks: New to agentic AI / Building / Running in production./book/index to show 18 chapters organized by 5 Parts with anchor IDs (#foundations, #part-1, #part-2, #part-3, #part-4) that match homepage BJO links.@astrojs/sitemap— generatessitemap-index.xml+sitemap-0.xmlat build, indexing all 55 published pages..github/workflows/astro-deploy.ymltrigger changed fromworkflow_dispatch(manual) topush: master..github/workflows/deploy.yml(mkdocs gh-deploy) DELETED.legacy-mkdocs-finalplaced on the last mkdocs master commit for rollback.Final build state
dist/(55 indexed by Pagefind, 5 redirect stubs)dist/sitemap-index.xmldocs/,mkdocs.yml) left in repo as legacy — not part of the deployTest Plan
pnpm install && pnpm test— expect 11/11 passingpnpm astro check— expect 0 errorspnpm build— expect ~60 pages built including Pagefind index + sitemappnpm devand spot-check at least one page from each content type:/agentic-ai/(homepage)/agentic-ai/start/(audience routing — NEW)/agentic-ai/book/(full TOC with 18 chapters by Part — NEW)/agentic-ai/book/00a-how-llms-work/(Foundations — NEW substantive port)/agentic-ai/book/01-what-agentic-means/(Part I opener — NEW)/agentic-ai/book/04-multi-agent-without-theater/(a stub chapter — NEW)/agentic-ai/patterns/(pattern index — NEW)/agentic-ai/patterns/workflow-first/(one pattern hub — NEW)What's deferred / not in this PR
baseline-eval-report.mdx19-vs-18 discrepancy (inherited from W3) — flagged as content-author follow-upog-default.png— still using fn-001 placeholder from W2draft, URLs preserved for SEO stabilityInherited known issues from W3
evaluating-and-hardening,failure-casesreconciliation tied to baseline 19-vs-18 inconsistency in source markdownSummary by CodeRabbit
New Features
Documentation