Skip to content

Clarify ghost's brand context router positioning - #304

Merged
nahiyankhan merged 2 commits into
mainfrom
docs/brand-context-router
Oct 10, 2026
Merged

nahiyankhan merged 2 commits into
mainfrom
docs/brand-context-router

Conversation

@nahiyankhan

@nahiyankhan nahiyankhan commented Oct 10, 2026 •

Copy link
Copy Markdown
Collaborator

Category: improvement
User Impact: New users can understand ghost, record one brand decision, and use it with their existing agent.

Problem: The READMEs mixed consumer setup with implementation detail and repeated the product thesis. Public descriptions also blurred the distinction between the agent selecting guidance and ghost delivering it.

Solution: Describe ghost as a brand context router for agents across GitHub, npm, and the site opening. Lead the READMEs with setup, a confirmed payment-failure rule that applies across email/errors/support, and reviewing the result; link out for technical detail. No CLI, API, or package-format behavior changes.

Validation:

  • pnpm run quality:all: passed through the pre-push hook, including builds, package/release checks, workspace checks, and guidance validation.
  • pnpm test: 332 passed, 1 skipped.
  • README smoke checks: the exact guidance example validates; gather/pull/stats work; npm links target existing repo paths; consumer sections match after URL adaptation.
  • Desktop (1280px) and mobile (375px) site inspection passed before the hero-line restoration. The restoration retains the original hero text/layout; docs build and typecheck pass.
  • git diff --check: passed. Existing non-blocking lint and cover-policy warnings remain unchanged.

Changeset: added .changeset/plain-readme.md as a patch for @design-intelligence/ghost.

ghost Review:

  • Current CLI has no ghost check command; package validation passed through quality:all.
  • node packages/ghost/dist/bin.js review --base origin/main --package apps/docs/.ghost --node principles --node composition --node visual-system: advisory packet assessed against the copy-only site changes. Typography, layout, materials, and motion remain unchanged.
  • The packet reports material/check coverage gaps for metadata and docs outside the site's bindings, plus the existing unreferenced docs-site node. These are advisory coverage gaps, not failed checks.
File changes
  • README.md: consumer-first walkthrough, router positioning, cross-task example, concise references.
  • packages/ghost/README.md: same consumer story with absolute links for npm.
  • apps/docs/src/components/Hero.astro: retain the original "likeliest thing" hero line, with router positioning and explicit agent-selection/CLI-delivery wording in the explanation below.
  • apps/docs/src/layouts/Base.astro: align the default title and description.
  • package.json and packages/ghost/package.json: align package descriptions without changing commands or dependencies.
  • .changeset/plain-readme.md: release note for the public documentation update.

Screenshots/Demos: Desktop and mobile screenshots inspected locally; not attached. The README includes a runnable guidance example.

@nahiyankhan
nahiyankhan marked this pull request as ready for review October 10, 2026 21:35
@nahiyankhan
nahiyankhan merged commit 438bae7 into main Oct 10, 2026
6 checks passed
@nahiyankhan
nahiyankhan deleted the docs/brand-context-router branch October 10, 2026 21:35
Sign up for free to 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.

1 participant