@archangel70/cosmo

v1.15.1

Published

a month ago

Local-first, multi-agent Astro website builder for Claude, Codex, Antigravity, and the command line.

0High
0Medium
0Low

Cosmo

Cosmo helps an AI coding assistant build a complete, original Astro website for you. You describe the business, answer questions, review the work, and approve important decisions. Cosmo organizes the project, checks the website, and remembers where you left off—even when you switch AI tools.

You do not need to know how to code. Cosmo supports Claude Code, Codex, and Google Antigravity.

Current version: 1.15.1

Quick install

If Node.js and your preferred AI coding assistant are already installed, open Terminal on a Mac or PowerShell on Windows and paste:

npm install --global @archangel70/cosmo

That command installs Cosmo for Claude, Codex, and Antigravity. You do not need GitHub access, a ZIP download, Git setup, a license key, or separate Cosmo installations.

Create an empty website folder, open it in your preferred assistant, and start Cosmo:

| Assistant | What to enter | | --- | --- | | Claude Code | cosmo | | Codex | $cosmo | | Google Antigravity | /cosmo |

If this is your first time using Node.js or an AI coding assistant, follow the steps below.

First-time setup

The whole process is:

Install Node.js once.
Install Claude Code, Codex, or Google Antigravity.
Paste one command to install Cosmo.
Create an empty folder for your website.
Open that folder in your chosen assistant.
Start Cosmo and answer its questions in normal language.

Before you begin

You need a Mac or Windows computer, an internet connection, Node.js, and at least one supported AI coding assistant. Your AI provider may require its own account or paid plan; Cosmo itself has no account or license key.

Step 1: install Node.js

Cosmo uses Node.js to build and preview websites. You do not need to learn Node.js; it only needs to be installed.

Open the official Node.js download page.
Download the LTS version for your computer.
Open the downloaded installer.
Accept the normal installation choices.
Finish the installation.

Cosmo requires Node.js 22.12 or newer.

Step 2: choose your AI coding assistant

Install at least one of these:

Claude Code: use Claude Desktop and select its Code area, or follow the Claude Code installation guide.
Codex: install and sign in to the Codex desktop app, IDE extension, or command-line version using the official Codex documentation.
Google Antigravity: install and sign in using the official Antigravity introduction.

Use whichever assistant and plan suit you. You can change assistants later without restarting the website.

Step 3: install Cosmo

This is the only part of the beginner setup that uses a terminal. It is one installation command.

On a Mac

Open Terminal. You can find it with Spotlight Search.
Copy and paste this command, then press Return:
```
npm install --global @archangel70/cosmo
```
Confirm that Cosmo is installed:
```
cosmo --version
```

You should see 1.15.1 or a newer version. Cosmo automatically installs its Claude, Codex, and Antigravity launchers.

On Windows

Open Windows Terminal or PowerShell from the Start menu.
Copy and paste this command, then press Enter:
```
npm install --global @archangel70/cosmo
```
Confirm that Cosmo is installed:
```
cosmo --version
```

You should see 1.15.1 or a newer version. Cosmo automatically installs its Claude, Codex, and Antigravity launchers.

Step 4: create your website folder

Open Documents in Finder or File Explorer.
Create a new folder for the website.
Give it a simple name, such as smith-plumbing-website.
Leave the folder empty. Cosmo will place the website files inside it.

Step 5: open the folder in your assistant

Open Claude Code, Codex, or Antigravity and choose the empty website folder you created. If your assistant asks whether to work locally, choose the local option.

Step 6: start Cosmo

Enter the instruction for your assistant:

Claude Code: cosmo (fallback: /cosmo:cosmo)
Codex: $cosmo (or ask, “Use Cosmo to build this site.”)
Google Antigravity: /cosmo

Cosmo will first explain the complete website journey, recognize what is already in the folder, and give you one clear next step. In a new folder, the first question is simply what the business or project is called and what it does.

From that point forward, Cosmo chooses the appropriate internal tools and tells you where you are in the process. You do not need to guess whether design, copywriting, page planning, development, or testing comes next.

Answer in normal language. You do not need to use special commands or technical terms. If you do not know an answer, say so. Cosmo should ask for clarification instead of inventing business facts.

If the assistant does not recognize Cosmo, close and reopen it, then run cosmo setup in Terminal or PowerShell and try again.

What happens next

Cosmo and your chosen assistant will guide you through these stages:

Business questions — what the business does, who it helps, and what the website should accomplish.
Brand direction — voice, personality, positioning, and approved business facts.
Copy strategy — what the reader believes now, the honest reason to choose the business, supporting proof, and the right next action.
Website design — several different visual directions before you choose one.
Homepage — the first complete page for your review.
Page plan — the remaining pages, their purpose, and how they connect.
Website build — the assistant writes each page from an approved Copy Studio brief and creates reusable design pieces.
Quality checks — Cosmo checks copy strategy, proof, links, content, mobile layouts, accessibility, and build errors.
Release and deployment — you approve the finished website and decide where it should be published.

Cosmo pauses at important decisions so you can review and approve them. It will not treat unfinished starter pages as a finished public website.

During setup, Cosmo also asks whether you want an optional AI-readable EntityMap. You can say yes without creating any API keys: Cosmo builds the core map from your approved website content. Optional services such as Google Knowledge Graph or TextRazor can be connected later if you want additional research signals.

Preview your website

Ask your assistant:

Show me a preview of the website.

Your assistant can start the local preview and give you a link. The link usually looks like http://localhost:4321. Open it in your browser.

If you are working directly in a terminal, run this from the website folder:

cosmo dev .

Press Control+C in the terminal when you want to stop the preview.

To let someone outside your computer view the site temporarily, ask your assistant:

Share this site with a temporary preview link.

Cosmo will give you a public trycloudflare.com address that works only while the preview command is running. Anyone with the address can open it, so do not use it for private or sensitive material. This is a review link, not a production deployment. The first time you use it, Cosmo may ask you to install Cloudflare's free cloudflared helper; no Cloudflare account or API key is required.

Continue later

Cosmo saves its progress inside the website folder. To continue another day:

Open Claude, Codex, or Antigravity.
Select the same website folder.
Start Cosmo using cosmo, $cosmo, or /cosmo as appropriate.

Cosmo will inspect the saved project and continue from the correct stage. You do not need the old conversation.

Use Cosmo with an existing website

Cosmo can work with an existing Astro website without deleting, redesigning, or converting its pages.

Make a backup or commit the existing website first.
Open the existing website folder in your chosen assistant.
Invoke Cosmo.
The assistant will identify the Astro project and ask whether you want Cosmo to adopt it.
Review the inventory before approving changes.

Adopted sites use a native-preservation workflow. Existing .astro pages, components, styles, design, and URL format remain authoritative. Cosmo inventories them and runs QA against the rendered website; it does not require moving pages into src/content/pages, using Cosmo section components, or changing file-format URLs such as /about backed by about.html.

Cosmo will not automatically adopt an unrelated folder or overwrite a folder it does not recognize. See Native Astro adoption for the preservation workflow and release requirements.

Update Cosmo

When a new version is announced, open Terminal or PowerShell and run:

cosmo update

Cosmo downloads the latest published version and refreshes its Claude, Codex, and Antigravity launchers. Your website projects are not changed. When the update finishes, close and reopen your AI assistant, then confirm the installed version:

cosmo --version

Updating from Cosmo 1.11.0 or older

Older versions do not have the cosmo update command yet. Run this longer command one final time:

npm install --global @archangel70/cosmo@latest

After that, use cosmo update for every future update.

If cosmo update reports a permissions or npm error, use the original installer as a fallback:

npm install --global @archangel70/cosmo@latest

Remove Cosmo

Run these commands in Terminal or PowerShell:

cosmo agent uninstall all
npm uninstall --global @archangel70/cosmo

Quick help

| Problem | What to do | | --- | --- | | node or npm is not recognized | Restart the terminal. If it still fails, reinstall the Node.js LTS version. | | cosmo is not recognized | Restart the terminal, then repeat npm install --global @archangel70/cosmo. | | Your assistant does not recognize Cosmo | Restart it, run cosmo setup, then use Claude's /cosmo:cosmo, Codex's $cosmo, or Antigravity's /cosmo. | | You opened the wrong folder | Stop before approving changes, create or select the intended website folder, and start again there. | | You do not know how to answer a question | Tell the assistant what you know and ask it to explain what information is missing. | | cloudflared is required for a shared preview | Install the free Cloudflare helper shown in Cosmo's message, then repeat the preview request. A Cloudflare account is not required. |

For additional problems, see Troubleshooting.

What Cosmo includes

Conversational launchers for Claude, Codex, and Antigravity.
A clean Astro website starter with no assumed business, location, or house style.
Safe adoption of existing Astro websites.
Guided business intake, brand discovery, Copy Studio, visual direction, page planning, generation, QA, release, and deployment.
Human approval steps for brand, design, homepage, templates, page plan, and final QA.
Built-in research, authority, local-business, editorial, regulated-topic, audience, search, conversion, writing, brand-language, image-direction, and Claude Design capabilities.
Checks for business facts, claims, proof, page purpose, links, accessibility, mobile layouts, and build quality.
Saved project state so any supported agent can continue without relying on the old chat.
Local previews, temporary public Cloudflare preview links, plus Cloudflare Pages, SFTP, FTPS, and explicitly acknowledged FTP deployment.
No license key, WordPress installation, hosted Cosmo account, or Cosmo cloud service.

Contents for advanced users

The rest of this README is a detailed reference. New users can stop here and let their chosen assistant guide the build.

How a Cosmo build progresses

| Stage | Outcome | Human approval | | --- | --- | --- | | Intake | Business, audience, goal, scope, and design mode | Automatic after validation | | Brand | Discovery, brand brief, entity canon, voice, and evidence ledger | Required | | Design | Explored direction, tokens, components, and captured manifest | Required | | Homepage | Approved homepage content and implementation | Required | | Template | Typed content model and reusable rendering system | Required | | Plan | Validated page inventory, intent, evidence, and link graph | Required | | Generate | Resumable page-production queue | Automatic after completion | | QA | Fresh passing integrity, content, static, intelligence, and browser reports | Required | | Release | One source-bound readiness decision and release ID | Deterministic check | | Deploy | Preview or exact READY production release | Operator initiated |

The repository is the source of truth. cosmo workflow resume . reconstructs the current stage and next action from local files, even when a different AI agent continues the work.

Intake and brand discovery

Create structured intake:

cosmo intake . \
  --niche "Residential architecture" \
  --audience "Homeowners planning a custom home" \
  --goal "Generate qualified consultations" \
  --location "Verified service region" \
  --pages 12 \
  --design-mode hybrid

Create and complete guided brand discovery:

cosmo brand discover .
cosmo brand check .

Discovery lives in .cosmo/brand/discovery.json. Complete it from supplied facts and approved synthesis, then set its approval only after the project owner explicitly approves it. Cosmo does not invent credentials, locations, customer knowledge, proof, results, or authority.

Advance the workflow through its gates:

cosmo workflow show .
cosmo workflow submit intake .
cosmo workflow submit brand .
cosmo workflow approve brand . --by "Project owner"
cosmo workflow resume .

Submission validates required files and selected capability artifacts. Approval is a separate, named human action.

Intelligence profiles and capability packs

Profiles select a maintained group of first-party capability packs. They govern what must be researched, recorded, reviewed, and checked; they do not impose a universal visual style.

| Profile | Best suited to | Included packs | | --- | --- | --- | | lean | Smallest core contract surface | No optional packs | | authority-site | Evidence-led authority site | Authority, research | | local-authority | Defensible regional/local site | Authority, local, research | | editorial-research | Publication or research-led site | Authority, editorial, research, image direction | | regulated-authority | Higher-risk subject with named review | Authority, editorial, regulated, research | | design-led | Independent art direction | Image direction, Claude Design | | growth-site | General business and lead generation | Audience, differentiation, conversion, naturalness, branded language | | search-authority | Search-informed authority/content site | Audience, authority, differentiation, research, search intelligence, naturalness | | brand-led | Distinctive brand and design system | Audience, differentiation, branded language, image direction, Claude Design | | full-authority | All available first-party gates | Every built-in pack |

Inspect and manage the selection:

cosmo intelligence list
cosmo intelligence show .
cosmo intelligence apply growth-site .
cosmo intelligence add image-direction .
cosmo intelligence remove image-direction .
cosmo intelligence scaffold .
cosmo intelligence guide brand .
cosmo intelligence check .

Built-in packs cover:

authority
local
editorial
regulated
research
audience-intelligence
differentiation
search-intelligence
conversion
editorial-naturalness
branded-language
image-direction
claude-design

Organizations may also import declarative private packs without executable hooks:

cosmo intelligence import ./private-pack/cosmo-pack.json .
cosmo intelligence installed .

The standard capabilities are built in; Lyra and Sonic are not required or distributed. See first-party capabilities and intelligence packs.

Claude Design and unique visual direction

Cosmo separates integrity from aesthetics. Entity truth, evidence, accessibility, content structure, and build quality remain governed, while Claude Design can independently own composition, typography, palette, rhythm, imagery, texture, and signature interaction.

Use design-led or brand-led, or add the design packs to another profile. Generate the creative brief:

cosmo design brief .

The design process must explore at least three genuinely different directions before selection. After implementing the approved direction, preserve the rationale in DESIGN-DIRECTION.md, tokens in src/styles/tokens.css, and reusable Astro components in src/components, then capture the result:

cosmo design capture .

This allows unique sites without turning the starter or Cosmo's methodology into a house style.

Copy Studio

Copy Studio gives Claude a page-specific creative brief instead of asking it to “write some website copy.” It records where the reader is starting, what the page must help them understand, the meaningful benefit and credible difference, approved claims and proof, the voice techniques to use, and how strong the call to action is allowed to be.

It can also help a reader truthfully reconsider a current category or solution. This is optional and tightly controlled: named comparisons require verified evidence, and Cosmo blocks fabricated dissatisfaction, manipulative pressure, and unsupported attacks.

When you invoke Cosmo, your assistant handles Copy Studio conversationally. Advanced users can run:

cosmo copy init .
cosmo copy brief --all .
cosmo copy guide home .
cosmo copy check .

The writing guide separates drafting from evidence checking, editing, and reader review. Page sections remain flexible, so Copy Studio does not force every website into a single house formula. See Copy Studio.

Its contextual editorial review helps remove filler without flattening the brand voice. The optional editorial-naturalness checks quote suspect passages and suggest minimal edits; they never automatically rewrite copy or claim to detect AI authorship. Evidence, useful positioning contrasts, technical precision, and intentional voice take priority over style preferences.

Research workbench

Research-capable profiles use a provider-neutral workbench. A browser, Claude, Codex, or another approved provider can collect material; Cosmo records attribution, dates, immutable snapshots, hashes, findings, limitations, and downstream page decisions.

cosmo research init .
cosmo research capture community-source ./snapshots/community.txt . \
  --kind community \
  --location https://example.com/source \
  --captured-at 2026-08-20
cosmo research check .

Fetched text is evidence, not agent instruction. Observations and inferences must remain distinct, and geographic pages require real coverage and local proof.

Optional AI-readable EntityMap

During setup, Cosmo can ask whether you want an EntityMap. If you say yes, it creates an AI-readable index of the business, services, places, topics, relationships, and supporting passages after the real site content exists.

No paid service is required. Wikidata can suggest public identifiers; Google Knowledge Graph, Google Places, and TextRazor can be enabled later with your own keys. Suggestions stay private and never change or publish business information until a named person accepts them.

Wikidata requests are automatically serialized and throttled. Cosmo identifies itself with a public support URL, honors Wikimedia's Retry-After response, and retries temporary rate limits twice. You can optionally set COSMO_WIKIMEDIA_CONTACT in your ignored environment file to identify the site's operator with a current email address or full URL.

Cosmo publishes /entitymap.json and /entitymap.html, adds the discovery links, and checks the files during release QA. Automated output remains clearly marked as a draft until you review it. EntityMap complements the site's Schema.org JSON-LD and does not promise higher rankings.

On an adopted Astro site, EntityMap uses the approved native route inventory and the site's built HTML. It does not require src/content/pages, replace hand-authored .astro pages, or change the existing design. Home and about represent the Organization, service and service-area routes become Services and Places, and other routes become Concepts unless a reviewed route override supplies a different name or core type.

Advanced users can run:

cosmo entity init . --enable
cosmo entity build .
cosmo entity enrich wikidata .
cosmo entity candidates .
cosmo entity accept <candidate-id> . --by "Project Owner"
cosmo entity check .
cosmo entity approve . --by "Project Owner"

entity build compiles the current draft without approving it. Enrichment providers are wikidata, googleKnowledgeGraph, googlePlaces, and textRazor; the Google and TextRazor providers read their keys from environment variables or an ignored file passed with --env-file. entity candidates shows private suggestions, and entity accept records one named human decision. Only entity approve changes the public map from generator draft to named self-declaration.

See EntityMap for provider setup, review safeguards, and generated files.

Integrity, evidence, and page planning

Initialize the integrity layer in an older Cosmo project or validate the current one:

cosmo integrity init .
cosmo integrity check .

The project-owned contracts include:

.cosmo/brand/entity-canon.json: canonical identity, domain, services, audiences, locations, people, and credentials.
.cosmo/brand/voice-profile.json: authorized voice evidence, vocabulary, boundaries, and examples.
.cosmo/evidence.json: claims, proof, provenance, verification state, and sources.
.cosmo/build-plan.json: routes, intent, indexability, audience need, claims, proof, and governed links.
.cosmo/work/pages/<id>/brief.json: plan-derived contract for one page.

Validate a draft or approved plan and derive page briefs:

cosmo plan check .
cosmo brief create --all .
cosmo brief create home . --replace

A draft plan can be reviewed, but generation and plan approval require approved: true. Every indexable claim must resolve to appropriate verified proof. Unsupported pages can remain noindex while evidence is pending; Cosmo does not silently make them publishable.

Resumable page generation

Prepare workspaces and start the bounded queue after plan approval:

cosmo generate workspace --all .
cosmo generate start . --max-pages 12
cosmo generate next .
cosmo generate advance home .
cosmo generate complete home .
cosmo generate status .

Pages progress through:

planned → briefed → sourced → outlined → drafted → edited → verified → done

Record failures and bounded repair explicitly:

cosmo generate fail home . --reason "Missing approved proof"
cosmo generate retry home .
cosmo generate repair home . --reason "CTA evidence relationship failed"

Prior state is retained. A third repair request escalates to human review instead of looping indefinitely.

Build, test, and browser QA

Day-to-day development commands:

cosmo dev .
cosmo build .
cosmo check .

Run the complete production-oriented checks:

cosmo integrity check .
cosmo content check .
cosmo intelligence check .
cosmo check .
cosmo browser check .

The checks cover:

Astro build output, metadata, canonical URLs, JSON-LD, internal links, robots rules, and sitemap coverage.
Entity consistency, intent, voice, evidence, provenance, duplication, CTA trust, and content substance.
Every selected intelligence-pack artifact and its real implementation consequences.
Rendered routes at 320, 768, and 1440 pixels.
WCAG A/AA issues, keyboard focus, runtime errors, and horizontal overflow.
Full-page screenshots and Lighthouse results.

Use --no-build when a current dist already exists. Use --no-lighthouse to skip Lighthouse during a browser-only diagnostic. If Chrome is in a non-standard location, set COSMO_CHROME_PATH to its executable.

Browser console and page errors normally block release. CSP messages explicitly marked Report Only are retained as non-blocking warnings, while enforced CSP failures remain critical. If a reviewed third-party tool emits another harmless diagnostic, add a narrow identifying substring to .cosmo/policies/browser-audit.json; Cosmo will keep the message visible as a warning instead of silently discarding it. See Browser QA for the policy format and safety guidance.

Release readiness

After workflow, generation, approvals, and QA are complete:

cosmo release check .
cosmo release show .

The release check writes DELIVERY.md and a machine-readable manifest. It blocks placeholder identity, missing approvals, zero indexable pages, incomplete generation, missing/failed/stale QA, capability-selection drift, or any source change after QA. A READY result has a source-derived release ID used by production deployment.

Preview and deployment

Deployment is optional. A Cosmo project remains a standard static Astro site whose dist directory can be hosted anywhere.

Start a production-style local preview:

cosmo deploy local .

Share a temporary preview

To let a client, friend, phone, or another assistant see the site before it is deployed, ask your assistant:

Share this site with a temporary preview link.

Or run:

cosmo preview share .

Cosmo builds the site, starts a private local preview, and uses Cloudflare Quick Tunnels to print one temporary public HTTPS address. No Cloudflare account, DNS change, deployment setup, or API key is required. The free cloudflared application must be installed; when it is missing, Cosmo prints the appropriate installation step.

Anyone who has the address can view the preview. The random address stops working as soon as you press Ctrl+C. It is for review only: Cosmo does not record it as a deployment, treat it as production, or use it to bypass QA and release approval. Use --no-build only when the current dist is already correct, and use --port 4173 only when you need a specific local port.

Install cloudflared once if Cosmo reports that it is missing:

Mac: run brew install cloudflared in Terminal.
Windows: download and run Cloudflare's current 64-bit MSI from the official cloudflared downloads page.
Linux: follow the distribution-specific instructions in Cloudflare's official package repository.

After installation, repeat cosmo preview share ..

Cloudflare Pages

Configure a Direct Upload project:

cosmo deploy configure cloudflare-pages . \
  --project my-project \
  --production-branch main

Authenticate Wrangler separately, then deploy:

cosmo deploy preview .
cosmo release check .
cosmo deploy production .

SFTP, FTPS, and FTP

SFTP is preferred:

cosmo deploy configure sftp . \
  --host files.example.com \
  --remote-dir /public_html \
  --preview-remote-dir /preview

Copy .env.example to the gitignored .env.deploy and provide values locally:

COSMO_DEPLOY_USER=hosting-user
COSMO_DEPLOY_PASSWORD=hosting-password
COSMO_DEPLOY_HOST_FINGERPRINT=SHA256:server-fingerprint

Deploy using the runtime credential file:

cosmo deploy preview . --env-file .env.deploy
cosmo release check .
cosmo deploy production . --env-file .env.deploy

SFTP supports private keys through --no-password, --private-key-env, and --passphrase-env. FTPS supports explicit TLS by default or --implicit for implicit TLS. Plain FTP transmits credentials and content without transport encryption and requires the explicit --allow-insecure acknowledgement.

File-transfer previews require a separate preview directory. Transfers are differential and non-destructive: only new or changed files upload, and Cosmo never deletes remote files implicitly. Credentials are loaded into memory and never written to project config, deployment history, manifests, or handoffs.

Inspect deployment state:

cosmo deploy status .
cosmo deploy history .

Production deployment accepts only the exact source represented by the recorded READY release. See deployment for every provider and credential option.

Cross-agent handoff

Create a durable handoff before changing tools or operators:

cosmo handoff create . \
  --from claude \
  --to codex \
  --note "Approved direction is implemented; continue with requested maintenance."

cosmo handoff show .

This writes HANDOFF.md and .cosmo/handoff.json, capturing workflow, generation, plan, QA, release, deployment, and the next action. Generated projects also include CLAUDE.md, AGENTS.md, and .agents adapters so supported tools work from the same contracts. The same command works for any transition, such as --from codex --to antigravity. New projects also contain .agents skills, rules, and workflows so each supported tool can recover the same process.

Command reference

Run cosmo help for the installed version's canonical syntax.

Setup and operation

| Command | Purpose | | --- | --- | | cosmo | Show the friendly, context-aware next step for the current folder. | | cosmo start [directory] | Show the guided next step for a specified folder. | | cosmo help | Show the complete developer command reference. | | cosmo update | Download the latest published Cosmo version and refresh all agent launchers. | | cosmo setup [--agent name] | Install or repair all launchers, or only Claude, Codex, or Antigravity. | | cosmo agent list | Show supported agents and whether each adapter is ready. | | cosmo agent install <name|all> [--replace] | Install or update one or every agent adapter. | | cosmo agent status [name|all] | Show adapter locations and start instructions. | | cosmo agent uninstall <name|all> | Remove adapters without deleting Cosmo or website projects. | | cosmo init [directory] [options] | Create a Cosmo Astro project in an empty directory. | | cosmo adopt [directory] [options] | Add Cosmo governance to an existing Astro project without replacing its source. | | cosmo claude install [--replace] | Backward-compatible shortcut for the Claude launcher. | | cosmo claude status | Show Claude launcher installation state. | | cosmo claude uninstall | Remove the Claude Code launcher without removing the CLI. | | cosmo doctor [directory] [--json] | Diagnose Node, npm, dependencies, Chrome, project access, and deployment state. | | cosmo status [directory] [--json] | Summarize project, workflow, plan, generation, QA, release, and deployment state. | | cosmo dev [directory] | Start Astro development mode. | | cosmo build [directory] | Produce the static Astro build. | | cosmo --version | Print the Cosmo version. |

Common init and adopt options are --name, --brand, --site, --profile, and --entity-map; adoption also accepts --design-mode.

Discovery, design, and research

| Command | Purpose | | --- | --- | | cosmo intake [directory] --niche ... --audience ... --goal ... | Write structured project intake. | | cosmo brand discover [directory] [--replace] | Create guided brand discovery. | | cosmo brand check [directory] | Validate completed, human-approved discovery. | | cosmo design brief [directory] [--agent claude\|codex\|antigravity] | Create the creative brief and guidance for the selected design agent. | | cosmo design capture [directory] | Capture implemented tokens and Astro components. | | cosmo research init [directory] [--replace] | Create the research workbench. | | cosmo research capture <id> <snapshot> [directory] [options] | Store an attributed, SHA256-bound research snapshot. | | cosmo research check [directory] | Validate research tasks, sources, findings, and candidates. | | cosmo copy init [directory] [--replace] | Create or intentionally reset the project copy strategy. | | cosmo copy brief <page-id> [directory] [--replace] | Create one page-specific annotated copy brief. | | cosmo copy brief --all [directory] [--replace] | Create briefs for every planned page. | | cosmo copy guide <page-id> [directory] | Print the approved staged writing guide for a page. | | cosmo copy check [directory] | Validate strategy, briefs, claims, proof, comparisons, and CTA limits. |

Additional intake options include --location, --pages, --language, --design-mode, and --replace. Research capture requires --kind and --location; it accepts --captured-at and --replace.

Intelligence and integrity

| Command | Purpose | | --- | --- | | cosmo intelligence list | List built-in profiles and packs. | | cosmo intelligence show [directory] | Show the active project selection. | | cosmo intelligence apply <profile> [directory] | Replace the selection with a profile. | | cosmo intelligence add|remove <pack> [directory] | Modify the active pack selection. | | cosmo intelligence scaffold [directory] [--replace] | Create required selected-pack artifacts. | | cosmo intelligence guide <stage> [directory] [--agent claude\|codex\|antigravity] | Print stage-specific questions and guidance for the selected agent. | | cosmo intelligence check [directory] | Evaluate selected capabilities against the project. | | cosmo intelligence import <package> [directory] [--replace] | Install a declarative private pack. | | cosmo intelligence installed [directory] | Show imported package locks. | | cosmo integrity init [directory] [--replace] | Add the integrity foundation to an older project. | | cosmo integrity check [directory] [--allow-missing-briefs] | Validate entity, voice, evidence, plan, capabilities, and briefs. | | cosmo entity init [directory] [--enable] [--replace] | Create or update the optional EntityMap configuration. | | cosmo entity build [directory] | Compile and validate the current EntityMap draft. | | cosmo entity check [directory] | Rebuild and report EntityMap findings for QA. | | cosmo entity enrich <provider> [directory] [--env-file path] | Save private enrichment candidates from Wikidata, Google, or TextRazor. | | cosmo entity candidates [directory] | List private enrichment candidates and their review status. | | cosmo entity accept <candidate-id> [directory] --by name | Accept one candidate with a named human reviewer. | | cosmo entity approve [directory] --by name | Record final named review and publish the approved declaration. | | cosmo plan check [directory] | Validate the current Build Plan. | | cosmo brief create <page-id> [directory] [--replace] | Derive one page brief. | | cosmo brief create --all [directory] [--replace] | Derive all planned page briefs. |

Workflow and generation

| Command | Purpose | | --- | --- | | cosmo workflow list [directory] | List installed workflows and validity. | | cosmo workflow start [directory] [--workflow id] | Start a workflow. | | cosmo workflow show|resume [directory] | Show current stage, artifacts, approval state, and instructions. | | cosmo workflow submit <stage> [directory] | Validate and submit a stage. | | cosmo workflow approve <stage> [directory] [--by name] | Record explicit operator approval. | | cosmo workflow import <workflow.json> [directory] | Import a safe project workflow. | | cosmo generate workspace <page-id> [directory] [--replace] | Create one page workspace. | | cosmo generate workspace --all [directory] [--replace] | Create all page workspaces. | | cosmo generate start [directory] [--max-pages n] | Start the approved bounded queue. | | cosmo generate next [directory] | Show the next page and required gate. | | cosmo generate advance|complete <page-id> [directory] | Advance or complete a page after validation. | | cosmo generate fail|repair <page-id> [directory] --reason ... | Record a failure or repair request. | | cosmo generate retry <page-id> [directory] | Return a failed page to production. | | cosmo generate status [directory] | Show page-by-page queue state. |

QA, release, handoff, and deployment

| Command | Purpose | | --- | --- | | cosmo check [directory] [--no-build] | Build and audit the static output. | | cosmo content check [directory] | Run semantic and evidence-aware content QA. | | cosmo browser check [directory] [options] | Run rendered responsive, accessibility, and Lighthouse QA. | | cosmo release check|show [directory] | Create or inspect the source-bound delivery decision. | | cosmo handoff create [directory] [options] | Create durable agent continuity files. | | cosmo handoff show [directory] | Display the current handoff. | | cosmo deploy configure <provider> [directory] [options] | Configure Cloudflare Pages, SFTP, FTPS, or FTP. | | cosmo deploy local [directory] [--no-build] | Run the production build locally. | | cosmo preview share [directory] [--no-build] [--port n] | Create a temporary public review link that ends when Cosmo stops. | | cosmo deploy preview|production [directory] [options] | Deploy review or READY production output. | | cosmo deploy status|history [directory] | Inspect deployment configuration and durable history. |

Browser options are --no-build and --no-lighthouse. Remote deployment accepts --no-build and --env-file.

Project anatomy

| Path | Purpose | | --- | --- | | src/ | Standard Astro pages, content, components, layouts, and styles. | | public/ | Static public assets. | | .cosmo/project.json | Project identity, stage, design mode, and local metadata. | | .cosmo/intake.json | Structured build intake. | | .cosmo/brand/ | Discovery, Entity Canon, and voice profile. | | .cosmo/copy/strategy.json | Approved reader, positioning, voice, proof, and competitive-transition strategy. | | .cosmo/evidence.json | Central claim and proof ledger. | | .cosmo/entities/ | EntityMap configuration, optional provider settings, accepted matches, and private candidates. | | .cosmo/intelligence/ | Active packs, artifacts, and private-package locks. | | .cosmo/build-plan.json | Typed page architecture and link graph. | | .cosmo/work/pages/ | Per-page integrity briefs, Copy Studio briefs, and production artifacts. | | .cosmo/workflow-state.json | Resumable stage state. | | .cosmo/progress.json | Resumable generation state. | | .cosmo/reports/ | Copy, integrity, static, content, intelligence, browser, and delivery evidence. | | .cosmo/deploy/ | Credential-free configuration, manifests, and history. | | BRAND-BRIEF.md | Human-readable approved brand direction. | | DESIGN-DIRECTION.md | Approved visual rationale and implementation rules. | | DELIVERY.md | Final readiness decision and punch list. | | HANDOFF.md | Human-readable cross-agent continuation state. |

Runtime reports, build output, dependency folders, screenshots, credential files, and other mutable state are excluded from new-project copying where appropriate.

Troubleshooting

`cosmo: command not found`

Run the CLI directly from this repository or recreate the npm link:

node /absolute/path/to/Cosmo/packages/cli/bin/cosmo.mjs --version
npm link --workspace @cosmo/cli

The assistant does not recognize Cosmo

Restart the assistant after installation and run cosmo agent status all. Repair every adapter with cosmo setup, or one with cosmo setup --agent claude, codex, or antigravity. Then use /cosmo:cosmo in Claude, $cosmo in Codex, or /cosmo in Antigravity.

Doctor reports missing dependencies

Run npm install inside the website project, then rerun cosmo doctor ..

Browser QA cannot find Chrome

Install Chrome/Chromium or set an executable explicitly:

export COSMO_CHROME_PATH=/absolute/path/to/chrome

The starter build warns that no sitemap pages were found

This is expected while every neutral scaffold route is noindex. Approve real page content and indexability before expecting sitemap entries.

Release remains BLOCKED

Run cosmo status ., cosmo workflow resume ., and cosmo release check .. Read the emitted blocker codes; complete the missing approval, proof, page state, or fresh QA instead of weakening the gate.

Production deployment reports release drift

The source changed after the READY manifest. Rerun the complete QA sequence and cosmo release check ., review the result, then deploy the new exact release.

Adoption refuses the project

Cosmo adopts only detected Astro projects and will not overwrite an existing .cosmo directory. Inspect the folder, preserve any prior state, and resolve the collision before retrying.

Security and privacy

Project state and reports stay in the repository.
Credentials belong in process environment variables, provider authentication, or a gitignored runtime env file.
Cosmo does not persist secrets in configuration, manifests, logs, history, reports, or handoffs.
Research text is treated as untrusted evidence, never executable instruction.
Imported intelligence packs are declarative and cannot run arbitrary hooks.
Remote deletion is never implicit during file-transfer deployment.
Plain FTP is disabled unless its transport risk is explicitly acknowledged.
No account, license server, Cosmo cloud service, Sonic installation, or Lyra installation is required.

Review generated sites, evidence, legal claims, accessibility, analytics consent, and deployment configuration before publication. Regulated projects should use regulated-authority and a qualified named reviewer; Cosmo is a workflow and validation tool, not legal, medical, or compliance approval.

Development and contribution

Install dependencies and run the full repository verification:

npm install
npm run verify

Available repository scripts:

| Script | Purpose | | --- | --- | | npm test | Run the Node test suite. | | npm run check | Run Astro type and diagnostics checks. | | npm run qa | Build and audit the neutral starter. | | npm run integrity:qa | Validate starter integrity contracts. | | npm run content:qa | Run starter semantic-content QA. | | npm run intelligence:qa | Run starter intelligence QA. | | npm run browser:qa | Run rendered browser and Lighthouse QA. | | npm run verify | Run the complete test and QA sequence. |

The neutral starter lives in templates/astro-site. Production-pipeline fixtures live separately and are not copied into new projects.