feat: DevEx dogfood + demo visir, practice retype, local TechDocs#6
Closed
agent-refr wants to merge 1 commit into
Closed
feat: DevEx dogfood + demo visir, practice retype, local TechDocs#6agent-refr wants to merge 1 commit into
agent-refr wants to merge 1 commit into
Conversation
…ype, local TechDocs Post-merge demo hardening, born from the first real demo attempt (which died on Node versions and then had no tour to follow). The demo visir moves into the repo proper as docs/demo-visir.md — the Guildhall grand tour: setup (with the Node 22/24 gotcha called out), verify checklist, timed click-path, honesty lines, fallbacks, Q&A. It attaches to the catalog through a new DevEx slice of Ravenline: team-devex (+ Freya) owns guildhall-portal, a Component representing this very Backstage instance — the seed's one non-fiction entity — whose visir annotation and entity links point at the tour. New users find the tour from inside the thing it tours. The practice Component is retyped per Cervator's steer: spec.type practice (a clear noun in Component-type position), entity renamed security-practice. Its entity links now jump straight to the standard, the paved-road template, and the remediation docs — the practice -> standard -> trials tie was previously invisible from the UI (file-only), which made demo surfing frustrating. The gildi Group gets matching links. The scorecard engine later turns this navigational tie into live data. TechDocs, fully local: both mock repos gain mkdocs.yml + index pages, and their Components carry backstage.io/techdocs-ref dir refs — no Git provider involved (answering the live-site question: not needed). Operational visar nest as docs/runbooks/ for now so plain TechDocs renders them — an interim convention noted in the design doc section 3.5, the seed README, and both index pages — until the parameterized runbooks plugin restores the top-level /runbooks home. smoke-catalog grows two checks (portal ingested with type portal, ownedBy team-devex): 19 checks, all passing. Full ws test gate green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (15)
📝 WalkthroughSummary by CodeRabbit
WalkthroughAdds a Vísir demo guide, interim runbook conventions, local TechDocs fixtures, expanded mock-org catalog entities, and smoke-test coverage for the new Guildhall portal and DevEx ownership relation. ChangesVísir catalog and mock-org flow
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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: 2
🤖 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 `@examples/mock-org/repos/tracking-api/docs/oncall-primer.md`:
- Line 5: Update the on-call documentation and mkdocs navigation so the carrier
webhook authentication-failure paging condition has a corresponding runbook and
nav entry, alongside the existing queue-backlog procedure; alternatively, remove
this condition from the paging description if no procedure should be added.
In `@examples/mock-org/repos/tracking-api/docs/runbooks/queue-backlog.md`:
- Around line 24-25: Update the poison-message step in the runbook to include
the supported parameterized command for parking the message, with an explicit
dead-letter topic placeholder, then add a confirmation step that verifies the
message reached that topic before filing the bug or proceeding. Preserve the
instruction not to delete the message.
🪄 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: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 8acf327a-b0d1-4bf1-acd6-8cdaad9f7a7b
📒 Files selected for processing (15)
docs/demo-visir.mddocs/plans/2026-07-10-guilds-skills-standards-design.mdexamples/mock-org/README.mdexamples/mock-org/guildhall/standards/release-readiness.yamlexamples/mock-org/org.yamlexamples/mock-org/repos/security-practice/docs/index.mdexamples/mock-org/repos/security-practice/docs/runbooks/rotate-leaked-credential.mdexamples/mock-org/repos/security-practice/mkdocs.ymlexamples/mock-org/repos/security-practice/standard.yamlexamples/mock-org/repos/tracking-api/docs/index.mdexamples/mock-org/repos/tracking-api/docs/oncall-primer.mdexamples/mock-org/repos/tracking-api/docs/runbooks/queue-backlog.mdexamples/mock-org/repos/tracking-api/mkdocs.ymlexamples/mock-org/software.yamlscripts/smoke-catalog.sh
There was a problem hiding this comment.
Caution
Inline review comments failed to post. This is likely due to GitHub's internal server error or limits when posting large numbers of comments. If you are seeing this consistently it is likely a permissions issue. Please check "Moderation" -> "Code review limits" under your organization settings.
Actionable comments posted: 2
🤖 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 `@examples/mock-org/repos/tracking-api/docs/oncall-primer.md`:
- Line 5: Update the on-call documentation and mkdocs navigation so the carrier
webhook authentication-failure paging condition has a corresponding runbook and
nav entry, alongside the existing queue-backlog procedure; alternatively, remove
this condition from the paging description if no procedure should be added.
In `@examples/mock-org/repos/tracking-api/docs/runbooks/queue-backlog.md`:
- Around line 24-25: Update the poison-message step in the runbook to include
the supported parameterized command for parking the message, with an explicit
dead-letter topic placeholder, then add a confirmation step that verifies the
message reached that topic before filing the bug or proceeding. Preserve the
instruction not to delete the message.
🪄 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: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 8acf327a-b0d1-4bf1-acd6-8cdaad9f7a7b
📒 Files selected for processing (15)
docs/demo-visir.mddocs/plans/2026-07-10-guilds-skills-standards-design.mdexamples/mock-org/README.mdexamples/mock-org/guildhall/standards/release-readiness.yamlexamples/mock-org/org.yamlexamples/mock-org/repos/security-practice/docs/index.mdexamples/mock-org/repos/security-practice/docs/runbooks/rotate-leaked-credential.mdexamples/mock-org/repos/security-practice/mkdocs.ymlexamples/mock-org/repos/security-practice/standard.yamlexamples/mock-org/repos/tracking-api/docs/index.mdexamples/mock-org/repos/tracking-api/docs/oncall-primer.mdexamples/mock-org/repos/tracking-api/docs/runbooks/queue-backlog.mdexamples/mock-org/repos/tracking-api/mkdocs.ymlexamples/mock-org/software.yamlscripts/smoke-catalog.sh
🛑 Comments failed to post (2)
examples/mock-org/repos/tracking-api/docs/oncall-primer.md (1)
5-5: 🩺 Stability & Availability | 🟠 Major | 🏗️ Heavy lift
Add the second paging runbook.
This line identifies carrier webhook authentication failures as a paging condition, but
examples/mock-org/repos/tracking-api/mkdocs.ymlexposes only the queue-backlog runbook. Add an authentication-failure procedure and nav entry, or remove it as an actionable paging path.🤖 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 `@examples/mock-org/repos/tracking-api/docs/oncall-primer.md` at line 5, Update the on-call documentation and mkdocs navigation so the carrier webhook authentication-failure paging condition has a corresponding runbook and nav entry, alongside the existing queue-backlog procedure; alternatively, remove this condition from the paging description if no procedure should be added.examples/mock-org/repos/tracking-api/docs/runbooks/queue-backlog.md (1)
24-25: 🩺 Stability & Availability | 🟠 Major | 🏗️ Heavy lift
Make the poison-message step executable.
Step 4 provides no parking command, topic name/placeholder, or confirmation step. The operator must still improvise the critical branch, despite the documented copy-paste-safe parameterized-runbook contract. Add the supported parking command and verify the message reached the dead-letter topic before proceeding.
🤖 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 `@examples/mock-org/repos/tracking-api/docs/runbooks/queue-backlog.md` around lines 24 - 25, Update the poison-message step in the runbook to include the supported parameterized command for parking the message, with an explicit dead-letter topic placeholder, then add a confirmation step that verifies the message reached that topic before filing the bug or proceeding. Preserve the instruction not to delete the message.
Author
|
Closing in favor of a follow-up PR that batches this with the aspect-module design round (practice-as-institution, aspect-as-repo, dual-door grafts, blocks+facets). Same branch, extended — will reopen as #7. |
Merged
3 tasks
Cervator
added a commit
that referenced
this pull request
Jul 16, 2026
feat: aspect-as-module — grafts with two doors, blocks + facets, live topology (+ #6 content)
This was referenced Jul 19, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/demo-visir.md): the Guildhall grand tour — setup (the Node 22/24 gotcha called out, learned the hard way), verify checklist, timed click-path, honesty lines, fallbacks, Q&A. Born from the first demo attempt, which had no tour to follow.team-devex(+ Freya) joins Ravenline and ownsguildhall-portal— a Component representing this very Backstage instance, the seed's one non-fiction entity. Its vísir annotation and links point at the tour, so new users discover it from inside the thing it tours.spec.type: practice(clear noun in Component-type position), entity renamedsecurity-practice. Entity links on the practice and its gildi now jump straight to the standard, paved-road template, and remediation docs — making the practice→standard→trials tie navigable from the catalog (it was file-only before; frustrating to surf).mkdocs.yml+ index pages; their Components carrybackstage.io/techdocs-ref: dir:…refs — no Git provider needed. Operational vísar nest asdocs/runbooks/(interim convention noted in design §3.5, seed README, and both index pages) until the parameterized runbooks plugin restores the top-level/runbookshome.Test plan
make smoke-catalog: 19/19 (MTL + Ravenline + portal, kinds and relations, headless real ingestion).ws test leidangr(fullmake cigate): all green.docs/demo-visir.md— it is the doc a brand-new user follows first.Related
runIn: local+ mkdocs — documented in the vísir and seed README, config unchanged.