Docs Overview
ShipGlows documentation is structured so a fresh agent can find the right context, understand the decision surface, and execute against explicit contracts instead of guessing from chat history.
Public Skill Pages
If you are evaluating ShipGlows from the outside, start with the skills hub. It shows the concrete workflow moves behind the framework without requiring you to read internal execution contracts first.
ShipGlows now carries an explicit decision-quality contract. Agents should prefer bounded professional work over shortcuts, and treat speed or cost as tie-breakers only after correctness, security, maintainability, relevant performance, and proof are already safe.
Read the decision contracts
The public mode page now shows which master skill to launch first,
which focused skills own narrower proof lanes, and which arguments
switch a workflow instead of describing the task. The Markdown
reference lives in shipglows_data/technical/operator-guides/skill-launch-cheatsheet.md.
ShipGlows now distinguishes the user-as-founder perspective from the
ShipGlows-owner perspective. Use #founder when the
conversation should optimize for business decisions, growth, and
clarity. Use #shipglows-owner when the conversation is
about ShipGlows itself or adjacent assets and needs portfolio-level
arbitration.
ShipGlows also supports named profiles such as
%Victoire, %Prudence,
%Ariane, %Adhesion, and
%SEO-specialist. They change how
the turn is arbitrated, but the router still picks the owner skill
and focus tags still stay separate.
If a conversation starts drifting, ShipGlows now supports lightweight
focus tags such as #partner, #offer,
#growth, #clarity,
#founder, #shipglows-owner,
#pitch, #portfolio,
#canon, #quality, #ship,
and #shipglows so you can pull the agent back to the
right contract without launching a whole new workflow.
If you want the shortest user path, the install page shows the marketplace command, the plugin-directory step, and the first command to run once ShipGlows is installed.
Open install instructionsIf you want the direct version first, the FAQ page covers the most common questions about documentation scope, skills, and framework behavior.
Open the FAQShipGlows now exposes a real indexed blog backed by an Astro collection, not just a few isolated long-form pages. That gives repurposing and editorial work a proper publishing target.
Open the blogShipGlows separates the content map from the governance layer that checks public content, claims, page intent, and Astro content schema boundaries before public copy drifts from delivered behavior.
Browse editorial governance
ShipGlows keeps durable private operator data out of the public
framework repository. The working tree under
~/.shipglows/private/data/ is intended to be a
separate Git repository for versioned private memory, while
ephemeral review queues should stay in different private paths.
sf-platform-parity checks product and technical parity across
supported surfaces before public docs claim platform support,
especially for Flutter and shared-code products.
For spec-first work, the spec now carries the durable skill-run history: which lifecycle skills ran, which model was used, what result was recorded, and which command should happen next.
Read the workflow doctrine
The ShipGlows TUI is an optional read-only dashboard installed by the
main ShipGlows setup. Operators can launch tui from a
terminal to scan projects, specs, tasks, audits, and diagnostics
without opening the Flutter app or giving the dashboard write
powers.
`sf-fix` can patch a local bug quickly, but the default is still a durable `BUG-ID`, compact `shipglows_data/workflow/BUGS.md` pointer, and detailed `shipglows_data/workflow/bugs/BUG-ID.md` dossier unless the issue is a narrow minor exception.
Open sf-fixShipGlows audits skill discovery metadata so the catalog remains usable by Codex and Claude Code. The public proof keeps the discovery budget visible instead of letting the skill catalog drift into unreadable prompt inventory.
Read the compatibility FAQRecommended Combos
These combinations are the fastest way to steer the agent toward the right business, content, or governance posture without writing a long correction message.
#offer #cta #clarity
Use when the page or message explains too much but still does not make the value proposition or next action obvious.
#partner #growth #roi
Use when the agent should choose the highest-leverage move instead of the easiest technical move.
#founder #growth #clarity
Use when the user is acting as a business owner and the answer should optimize for useful decisions, growth, and clarity.
#shipglows-owner #partner #no-drift
Use when the conversation is about ShipGlows itself or adjacent assets and needs portfolio-level arbitration.
#end-user #clarity #quality
Use when the solution works technically but still feels too hard for a normal user.
#faq #trust #clarity
Use when the message needs to answer doubts directly and earn credibility.
#canon #drift #single-source
Use when code, docs, or public surfaces are out of sync and the source of truth matters more than local patching.
#shipglows #proof #contract
Use when the target is the internal ShipGlows system and the output should strengthen doctrine, proof, or internal execution quality.
Terminal TUI
The TUI is built for quick orientation on remote shells and phone-sized terminals. It reads the same ShipGlows Markdown sources as the rest of the workflow and keeps execution inside the skills layer.
tui
The installer provisions the TUI for configured users. After
sudo ./cli/install.sh and a fresh shell, the daily command is
tui. Longer aliases remain available as
sftui, sf-tui, and
shipglows-tui.
V1 can navigate projects, specs, tasks, audits, and diagnostics. It does not write Markdown, run shell commands, manage auth, or store cloud credentials. That boundary keeps the dashboard useful without turning it into an unsafe action surface.
Gum remains useful for one-shot shell prompts. The Flutter app stays a separate product surface. The terminal TUI is the persistent local cockpit between those two: faster than opening a full app, but still intentionally narrower than a write-capable workflow.
Governance Layout
shipglows_data/.
Root Markdown files are intentionally narrow. Business, product, GTM,
technical context, content maps, specs, bug records, research, reviews,
audits, and verification reports belong in the project-local
shipglows_data/ corpus where skills and the linter can
find them consistently.
Keep README.md, AGENT.md,
AGENTS.md as a symlink to AGENT.md,
optional CLAUDE.md, and optional public
CHANGELOG.md. Other ShipGlows governance docs should
move into shipglows_data/.
A root BUSINESS.md, CONTENT_MAP.md,
CONTEXT.md, GUIDELINES.md,
TASKS.md, or AUDIT_LOG.md is not
compliant just because it exists or has valid metadata. It should
be migrated to the canonical path and then linted there.
Use sf-docs migrate-layout to inventory root legacy
files, detect collisions, move safe artifacts, update references,
and run ShipGlows metadata compliance checks.
BUSINESS.md shipglows_data/business/business.md PRODUCT.md shipglows_data/business/product.md BRANDING.md shipglows_data/branding/branding.md GTM.md shipglows_data/business/gtm.md CONTENT_MAP.md shipglows_data/editorial/content-map.md CONTEXT.md shipglows_data/technical/context.md CONTEXT-FUNCTION-TREE.md shipglows_data/technical/context-function-tree.md ARCHITECTURE.md shipglows_data/technical/architecture.md GUIDELINES.md shipglows_data/technical/guidelines.md TASKS.md shipglows_data/workflow/TASKS.md AUDIT_LOG.md shipglows_data/workflow/AUDIT_LOG.md specs/*.md shipglows_data/workflow/specs/*.md Location Doctrine
We avoid doc drift by separating root discovery files from project-owned governance documents. This keeps each repository clean and easier to onboard for both agents and operators.
In adopted project repos, canonical ShipGlows Markdown lives in `shipglows_data/` under categories like `business`, `technical`, `editorial`, `workflow`, and `research`.
Read canonical-path rulesCompatibility entrypoints remain at repository root: `README.md`, `AGENT.md`, `AGENTS.md` as a symlink, optional `CLAUDE.md`, and optional public `CHANGELOG.md`.
Read canonical-path rulesUse `skills/references/canonical-paths.md` for ownership-based resolution before creating or moving project docs.
Read canonical-path rulesCore Navigation
Where a fresh agent should look first depending on the task.
Open in docs policyHow to orient quickly in the repo, identify hotspots, and route edits.
Open in docs policyHow to navigate large procedural shell files without re-reading everything.
Open in docs policyHow the optional terminal cockpit stays read-only, local, and separate from skill execution.
Open in docs policyWhere content lives: docs, landing pages, semantic clusters, public surfaces, and repurposing destinations.
Open in docs policyHow public content, claims, page intent, and Astro content schema boundaries stay aligned.
Open in docs policyWhy ShipGlows chooses correctness, security, maintainability, relevant performance, and proof before speed or convenience.
Open in docs policyMarkdown reference for master skills, supporting skills, and argument modes.
Open in docs policyPublic cheatsheet for lightweight recentering tags across business, content, governance, execution, and system focus.
Open in docs policyPublic overview, positioning, onboarding, and high-level framework story.
Open in docs policyThe execution doctrine behind sf-spec, sf-ready, sf-start, and sf-verify.
Open in docs policyDecision Contracts
Business, product, brand, GTM, architecture, and guidelines are kept separate on purpose. That separation avoids duplicate logic, stale context, and conflicting contracts.
For whom the product exists, what value it creates, and what model it may support.
Open in docs policyWhat the product does, which workflows matter, and which non-goals should stay out.
Open in docs policyHow the product should sound, what it can claim, and how trust is earned.
Open in docs policyHow the product is presented publicly, which objections matter, and what proof supports it.
Open in docs policyThe default quality bar for routing, model choice, implementation, fixes, and verification.
Open in docs policyHow the system is organized, where boundaries sit, and which invariants hold.
Open in docs policyHow contributors should work inside the repo and which technical rules stay stable.
Open in docs policyRemote Agent Access
Hosted MCP providers can ask Codex to complete an OAuth flow. When Codex runs remotely, the browser callback still lands on local `127.0.0.1`. ShipGlows documents that boundary so operators understand why a temporary SSH callback tunnel is part of the login workflow.
The provider redirects the browser to a localhost callback URL. If Codex is running on a server, that localhost address is otherwise the wrong machine.
The local tooling captures the fresh callback port, opens an SSH `-L` tunnel for that port, and closes it after the login flow. The app tunnels used for development remain separate.
Read the dedicated guideThe tunnel does not replace OAuth and does not make ShipGlows a token store. It only gives the local browser a route back to the remote Codex process during authorization.
Pragmatic Tooling
For small tooling such as the metadata linter, the question is not which language looks the cleanest in isolation. The question is which runtime is most likely to already exist on dev machines, Linux servers, CI workers, and VPS targets.
The linter uses the Python standard library only. That keeps it dependency-free, coherent with the repo, and more likely to run without extra setup than a Ruby-based equivalent on the targets ShipGlows cares about.
Installing Ruby just for a linter is rarely lighter in practice. If ShipGlows ever needed an even smaller runtime surface, the real alternatives would be Bash for very simple rules, Node in a JS-heavy repo, or a Go binary for zero external runtime at a much higher implementation cost.
Tracking Discipline
ShipGlows treats project tracking as local-first. Each repository keeps
its active workflow state in its own shipglows_data/ corpus,
while old central files are migration evidence rather than active truth.
shipglows_data/workflow/TASKS.md is the operational
tracker for one repository. Portfolio views are derived from local
project corpora instead of maintained in a separate central tracker.
If a legacy central archive contains completed work, that history can be imported as useful context. It should not be copied mechanically into a local backlog as if it were still active work.
ShipGlows re-reads legacy project history only as migration evidence, then separates active backlog from historical completed context. The local tracker should stay cleaner and more project-shaped than any old archive it was derived from.
shipglows_data/workflow/TASKS.md and
shipglows_data/workflow/AUDIT_LOG.md remain operational
trackers. A spec-first chantier records its own flow in the spec through
Skill Run History and Current Chantier Flow.
ShipGlows should not say “the tracker did not exist” without naming
which level it means: the master tracker, the project section inside
it, or shipglows_data/workflow/TASKS.md.
Execution Logic
The context layer tells the agent where to start. The decision contracts tell it what matters. The workflow doctrine tells it how to move from ambiguity reduction to verified delivery.