Frontmatter
| title | docs(readme): replace dead Quickstart links with portal learning URLs (#14493) |
| author | neo-opus-grace |
| state | Merged |
| createdAt | Jul 2, 2026, 6:16 PM |
| updatedAt | Jul 2, 2026, 6:24 PM |
| closedAt | Jul 2, 2026, 6:24 PM |
| mergedAt | Jul 2, 2026, 6:24 PM |
| branches | dev ← docs/14493-readme-quickstart-links |
| url | https://github.com/neomjs/neo/pull/14495 |
| contentTrust | |
| projected | |
| quarantined | 0 |
| signals | [] |
PR Review Summary
Status: Approved
🪜 Strategic-Fit Decision
Per §9 Strategic-Fit Step-Back:
- Decision: Approve
- Rationale: This is the right same-PR fix for the close target: a docs-only Quickstart link repair that removes stale deployment-path links and replaces the user-facing CTAs with source-backed portal learning routes. There is no blocking defect here; an Approve+Follow-Up would just turn the explicitly out-of-scope Examples/Blog route work into review churn.
Peer-Review Opening: Reviewed as the requested cross-family gate for the README Quickstart dead-link fix. The patch is small, but it sits on the onboarding front door, so I treated the link authority and close-target scope as the real review surface.
🧭 Patch-Blind Premise Snapshot
- Inputs Read Before Patch: Issue #14493, the changed-file list (
README.mdonly), the currentorigin/devREADME Quickstart section,learn/tree.json,apps/portal/view/learn/MainContainerController.mjs, the PR body/commit close-targets, and a KB sweep for README Quickstart / portal learning route authority. - Expected Solution Shape: A correct fix should make Quickstart links use durable learning-content targets: either
learn/markdown or portal learning routes backed bylearn/tree.jsonids. It must not hardcode deployment build paths likedist/production, and it should not replace dead links with routes absent from the portal learning tree. Test isolation is static/docs-focused: exact-head diff checks, route-id membership, portal route-source confirmation, and CI green are sufficient. - Patch Verdict: Matches. The diff replaces the five stale Quickstart CTAs with four portal learning links, the three deep-link ids are present and not hidden in
learn/tree.json, and the portal controller maps both/learnand/learn/{*itemId}withroutePrefix='/learn'. - Premise Coherence: Coheres with verify-before-assert and friction-to-gold: the operator-flagged onboarding friction is fixed by grounding README links in the committed learning-tree substrate instead of stale deployment URLs.
🕸️ Context & Graph Linking
- Target Epic / Issue ID: Resolves #14493
- Related Graph Nodes: Parent epic #14310;
learn/tree.json;apps/portal/view/learn/MainContainerController.mjs; README Quickstart onboarding surface
🔬 Depth Floor
Challenge OR documented search (per guide §7.1):
Documented search: I actively looked for stale dist/production / learning .github/ targets in the Quickstart block, missing or hidden learn/tree.json ids for the new deep links, stale magic-close targets in the branch commit, and portal route-source mismatch for /learn/{*itemId}. I found no blocking concerns.
Rhetorical-Drift Audit (per guide §7.4):
- PR description: framing matches the diff; the static route evidence is declared as L1 and live-site clickthrough is correctly left to Post-Merge Validation.
- Anchor & Echo summaries: N/A — README link labels only, no new code summaries.
-
[RETROSPECTIVE]tag: N/A — no tag used. - Linked anchors: #14493 and #14310 are used in their correct relationship roles.
Findings: Pass.
🧠 Graph Ingestion Notes
[KB_GAP]: None.[TOOLING_GAP]: None.[RETROSPECTIVE]: README learning links should resolve throughlearn/tree.json/ portal learning routes or committedlearn/markdown, not build-output deployment paths.
N/A Audits — 📑 📡 🔗
N/A across listed dimensions: no public API/contract surface, no MCP OpenAPI tool descriptions, and no workflow/skill convention introduced by this README-only patch.
🎯 Close-Target Audit
For every issue named as close-target, verify it does NOT carry the epic label:
- Close-targets identified: #14493
- For #14493: confirmed not
epic-labeled; labels are documentation/enhancement/ai.
Findings: Pass. Branch commit subject/body and PR body close only the delivered leaf #14493.
🪜 Evidence Audit
- PR body contains an
Evidence:declaration line. - Achieved evidence is sufficient for the close target: L1 static evidence covers a README-only link target correction whose ACs require removing banned target forms and verifying portal ids against
learn/tree.json. - Residuals: none for #14493; live neomjs.com clickthrough is listed as Post-Merge Validation rather than overclaimed as reviewed runtime evidence.
- Evidence-class collapse check: review language does not promote the static source check into live production-site proof.
Findings: Pass.
🧪 Test-Execution & Location Audit
- Branch checked out locally at exact head
d9b73557843f2423762483e9a40ba768ed0249cd. - Canonical Location: N/A — no test files added or moved.
- If a test file changed: N/A.
- If code changed: N/A — docs-only README change.
Findings: No tests needed for the docs-only diff. I verified git diff --check origin/dev...HEAD, the README Quickstart block, absence of banned Quickstart targets, the three learn/tree.json ids (gettingstarted/Setup, benefits/WhatIsNeo, agentos/OwnAgentTeam) with hidden:false, the portal /learn routing source, and current-head CI 6/6 green.
📋 Required Actions
No required actions — eligible for human merge.
📊 Evaluation Metrics
Verdict weights: 30% premise / right thing, 30% architecture + placement, 30% diff correctness, 10% AC/audit sanity. These are importance-to-verdict weights, not effort budgets.
[ARCH_ALIGNMENT]: 96 - The patch uses the committed learning tree and portal route controller as the source of authority, and avoids deployment-output URLs. The only small deduction is that live production clickthrough remains post-merge validation rather than something this static review can prove.[CONTENT_COMPLETENESS]: 96 - PR body names the dropped Examples/Blog scope, evidence level, tests, and post-merge validation; the README labels are concise and user-facing.[EXECUTION_QUALITY]: 98 - Exact-head static checks, route-id checks, and CI are clean; no code or test-surface risk introduced.[PRODUCTIVITY]: 100 - Fully satisfies #14493 by removing all banned Quickstart targets and replacing them with valid learning-section destinations.[IMPACT]: 65 - Small diff, high user-facing ROI because it fixes the first onboarding CTA cluster.[COMPLEXITY]: 15 - One README section with three source-authority checks; low implementation complexity.[EFFORT_PROFILE]: Quick Win - Low-complexity docs patch with direct onboarding value and clean validation evidence.
Approved for human merge once the normal human-only merge gate is exercised.
Resolves #14493
Fixes the README Quickstart — every CTA pointed at a dead target (
.github/files ordist/productionportal URLs whose deploy path is gone). Operator-flagged (@tobiu): "every user that uses those links is a lost one forever."Replaces the 5 dead links with 4 verified portal learning-section links. Per the operator's rule, README learning links target ONLY
learn/markdown OR the portal learning section (neomjs.com/#/learn/<id>— nav tree + live component previews + prev/next, superior for humans). The invariant: everylearn/**.mdregistered inlearn/tree.jsonis a live portal page, so tree.json membership = a guaranteed-live route..github/GETTING_STARTED.mdneomjs.com/#/learn/gettingstarted/Setupgettingstarted/Setup✓dist/production/…/#/learn/gettingstarted.Setup(stale.sep)neomjs.com/#/learn.github/AI_QUICK_START.mdneomjs.com/#/learn/agentos/OwnAgentTeamagentos/OwnAgentTeam✓neomjs.com/#/learn/benefits/WhatIsNeobenefits/WhatIsNeo✓Evidence: L1 (static — each portal id V-B-A'd against
learn/tree.json; docs-only, no runtime AC).Deltas from ticket
Examples + Blog dropped from the original 5-link list: neither is in
learn/tree.jsonand their old#/examples/#/blogroutes no longer exist in portal source — linking them would mint new dead links. Re-add once live routes are confirmed (flagged to operator). Read Next VISION/STORY.github/links are a separate, out-of-scope finding (those files physically live in.github/, so relocating them is its own decision).Test Evidence
learn/tree.json(gettingstarted/Setup,benefits/WhatIsNeo,agentos/OwnAgentTeam); the#/learnhub route confirmed inapps/portalsource.git diff --checkclean.Post-Merge Validation
dist/esm/apps/portal/#//#/all drift acrosslearn/blog/*+ guides) as a #14310 / #14327 leaf.Commits
d9b735578—docs(readme): replace dead Quickstart links with portal learning URLs (#14493)Authored by Grace (@neo-opus-grace, Claude Opus 4.8). Operator-flagged (@tobiu). Parent epic #14310.