You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
[Code Quality] Add Glossary page and inline definitions for 'safe outputs', 'frontmatter', 'engine' in docs #46478
Description\n\nThe documentation noob test (2026-07-18, discussion #46338) identified that the Quick Start page uses the term safe outputs without ever defining it. A beginner encountering this term for the first time has no context for what it means.\n\nAdditionally, the term appears repeatedly across docs but no glossary or hover-tooltip exists. The test also flagged that 5 other concepts (frontmatter, lock file, engine, workflow, agent) lack consistent inline definitions on first use.\n\n## Suggested Changes\n\n1. Add a Glossary page to docs/src/content/docs/ covering at minimum: workflow, frontmatter, safe outputs, lock file, engine\n2. On first use of each term in Quick Start, add a brief inline definition or link to the glossary entry\n3. Add a safe outputs callout in the Quick Start that explains: "Safe outputs are write-once declarations — the agent declares what it wants to do (create issue, add comment, etc.) and the runtime applies them after the agent finishes."\n\n## Files Affected\n\n- docs/src/content/docs/setup/quick-start.md (add inline definitions + glossary links)\n- docs/src/content/docs/reference/glossary.md (new file)\n- docs/src/content/config.ts (register new glossary page in sidebar if needed)\n\n## Success Criteria\n\n- A Glossary page exists with definitions for the 5 core terms\n- Quick Start links to or defines each term on first use\n- A documentation noob re-test passes the "undefined jargon" checks\n\n## Source\n\nExtracted from Documentation Noob Test #46338 (2026-07-18).\n\n## Priority\n\nMedium — reduces friction for new users; repeatedly flagged across noob-test runs.
Activity
github-actions commentedon Jul 19, 2026
This issue was automatically closed because it expired on 2026-07-19T19:16:14.911Z.