Skip to content

feat: homepage onboarding flow and AI-native software templates - #96

Merged
johnnyhuy merged 1 commit into
mainfrom
move-onboarding-homepage-87-88
Aug 24, 2026
Merged

feat: homepage onboarding flow and AI-native software templates#96
johnnyhuy merged 1 commit into
mainfrom
move-onboarding-homepage-87-88

Conversation

@johnnyhuy

Copy link
Copy Markdown
Contributor

Closes#87
Closes#88

#87 — Homepage onboarding flow

Reorients the homepage around first-use orientation without removing catalog surfaces:

  • Start here panel (directly under the hero): three concrete first actions — create your first service (/self-service), browse the docs (/docs), register an existing repo (/catalog-import). Replaces both the one-line Getting Started? alert and the near-identical Quick Actions grid (consolidated rather than duplicated; API Explorer moved to the sidebar).
  • Onboarding Docs section: surfaces up to 4 catalog entities tagged onboarding or getting-started as cards linking to their TechDocs pages. Skeleton loaders while loading, graceful empty state explaining the onboarding tag when none exist.
  • Support & Reference sidebar panel: replaces Quick Links with Documentation, API Reference, Notifications, and Get Help. The Get Help link is entity-driven — it points at the docs of a support-tagged entity when one exists, falling back to /docs.
  • Removed the duplicate Getting Started sidebar card (per PRD note).
  • All new links carry descriptive aria-labels; cards stack vertically at ≤600px via the existing Grid breakpoints; no hard-coded hex, all colours via theme.palette.*.
  • New portal-docs TechDocs entity (examples/portal-docs/) with Getting Started and Support & FAQ pages, tagged onboarding / getting-started / support, so the new sections have real content on first boot.

#88 — Reusable software templates

  • Family/provider tagging on all existing templates: family:repo, family:docs, provider:github, provider:gitlab; the two docs-site templates now carry recommended too.
  • Homepage Popular Templates now filters to recommended-tagged templates and renders a family chip on each card; the action button reads "See All Templates".
  • New AI-native templates (informed by the April 2026 CoE notes on AI-native repo patterns — every skeleton ships a concise AGENTS.md, TechDocs site, Dockerfile, and catalog registration):
    • ai-hub-service — provider-agnostic LLM gateway (/healthz, /v1/answer stub, src/providers/ interface)
    • answer-engine-worker — queue consumer + document indexer + query API (/v1/ask, /v1/index), delegates inference to an AI Hub via AI_HUB_URL, answers always carry citations
    • mcp-server — stdio MCP server with ping/echo example tools (@modelcontextprotocol/sdk)

Template consolidation/renames from the PRD were deliberately skipped to avoid scope creep (PRD note: "leave them as-is").

Verification

  • yarn lint — clean
  • mise run test — 9 passed, 1 skipped (pre-existing suite)
  • All template.yaml / catalog YAML parse clean
  • All three TS skeletons type-check clean (tsc --noEmit) with their declared deps

Manual QA checklist

  • / with no onboarding-tagged entities → Onboarding Docs shows empty state
  • / with portal-docs registered → card renders, links to /docs/default/component/portal-docs
  • GitHub Light / Dark / Legacy themes → all new sections honour theme
  • Mobile ≤600px → cards stack, no horizontal scroll
  • /self-service → Recommended group shows all 7 templates; family tags visible
  • Scaffold ai-hub-service end-to-end → repo created, entity in catalog, TechDocs builds

Notes

  • Curate plugin showcase for templates GitHub and answer engine #86 (plugin showcase for answer engine) is adjacent but not merged here — this PR ships the templates side; plugin/extension curation can stay separate.
  • The two pre-existing tsc errors (cli tsconfig lib entry, permission module type annotation) are unrelated to this change.

#87: reorient homepage around first-use orientation
- replace one-line Getting Started alert with a Start here panel
(create first service, browse docs, register existing repo)
- surface onboarding/getting-started tagged docs as homepage cards
with skeleton loaders and an empty state
- replace Quick Links sidebar with Support & Reference (docs, API
reference, notifications, get help) with entity-driven help link
- drop the duplicate Getting Started sidebar card
- add aria-labels to new navigation affordances
- ship portal-docs TechDocs entity (getting started + support/FAQ)
tagged onboarding/getting-started/support
#88: curate template inventory around three families
- tag existing templates with family:repo/docs and provider:github/gitlab
- homepage Popular Templates now filters to recommended and shows a
family chip on each card
- add ai-hub-service template (provider-agnostic LLM gateway skeleton)
- add answer-engine-worker template (queue consumer + indexer + query
API, AI Hub backed, cited answers)
- add mcp-server template (stdio MCP server with example tools)
- every new template ships AGENTS.md, TechDocs site, Dockerfile, and
catalog registration per the AI-native repo pattern
Co-authored-by: opencode-agent[bot] <219766164+opencode-agent[bot]@users.noreply.github.com>
@johnnyhuy
johnnyhuy merged commit 5321b9b into mainAug 24, 2026
5 checks passed
@johnnyhuy
johnnyhuy deleted the move-onboarding-homepage-87-88 branch August 24, 2026 12:34
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Package reusable software templates and starter structures Move onboarding and support docs into the homepage flow

1 participant

@johnnyhuy