@percepta/create

Scaffold and manage Mosaic packages.

Usage

npx @percepta/create

That's it. Outside a monorepo, the CLI prompts you for the customer slug, repo name, package type, and package name as needed. Defaults yield a running app — sign in as [email protected] / password.

Options (mostly for automation)

The bare command above is the canonical UX. The flags below exist for tests and other automation, not for routine use:

| Option | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | -t, --type <type> | Package type: monorepo, webapp, or library (skips the type prompt) | | --name <name> | Package/app name (skips the package name prompt) | | --customer <slug> | Customer slug stored in the generated monorepo workspace manifest | | --repo-name <name> | Repo name when creating a new monorepo (skips the repo name prompt) | | --cwd <dir> | Run as if the CLI was started from <dir> | | --skip-install | Skip dependency installation, which also skips the auto-run setup + dev + browser, leaving you with manual next-steps | | --non-interactive | Skip all prompts; values come from flags or defaults. Requires --name (or, for --type monorepo, --repo-name / --customer — that scaffolds a bare monorepo) | | -y, --yes | Alias for --non-interactive |

Subcommands

• create (default) — scaffold a new Mosaic package
• add — add a webapp or library to the current monorepo
• infra register-os-blueprint — open or update an infra PR for this customer monorepo's OS blueprint
• infra register-app <app> — open or update an infra PR for a webapp service, blueprint installation, and database

Project types

create auto-detects whether you're inside an existing pnpm monorepo (by walking up for pnpm-workspace.yaml) and changes its prompts accordingly:

• Outside a monorepo — you're asked for the customer slug, then the repo name, which defaults to <customer>-os. Then choose whether to initialize with a webapp (Y/n, default Y). Picking the webapp option also asks for the webapp name and scaffolds it inside packages/<webapp-name>/. Declining gives you an empty monorepo.
• Inside a monorepo — pick Webapp (default) or Library to add a new package under the workspace pattern.

Generated monorepos include a root .mosaic-workspace.json with the customer slug plus template compatibility metadata, and a pinned pnpm mosaic script. Prefer the workspace-owned command when adding packages:

pnpm mosaic add webapp my-app
pnpm mosaic add library my-lib

That command uses the create package version and template compatibility versions the monorepo was created with, so a newly added app does not silently drift to a newer scaffold.

Happy-path: zero-friction webapp

When you scaffold a webapp (the default flow), create automatically runs:

1. pnpm install (at the monorepo root)
2. pnpm run setup — root Docker Compose services + local database creation + Drizzle migrations + seed users
3. pnpm dev — Next.js dev server
4. Opens the served URL in your default browser

Sign in as [email protected] / password to start building.

To bail out of the auto-run and get manual next-steps instead, pass --skip-install. Then you can run install / setup / dev yourself when ready.

The webapp template ships with:

• Next.js 15 with App Router
• Authentication via Better Auth
• Database with PostgreSQL and Drizzle ORM
• Type-safe API with tRPC
• Background Jobs with Inngest
• Observability with OpenTelemetry, Langfuse, and Grafana Faro
• Styling with Tailwind CSS v4

The library template ships with TypeScript, ESLint, and a minimal src/index.ts.

The monorepo template ships with pnpm-workspace.yaml, root local Postgres/SpiceDB Docker Compose, root scripts (setup, dev, build, lint, test), strict tsconfig.json, flat-config ESLint, and an empty packages/ directory.

Customer OS blueprint

After creating a customer monorepo, register the customer OS blueprint in Percepta-Core/infra:

pnpm mosaic infra register-os-blueprint

Registration reuses the customer's existing AccessPolicy under ryvn/access/<customer>/, or creates ryvn/access/<customer>/<customer>-engineers.accesspolicy.yaml if none exists. The same PR registers the repository-specific <repo>-access-control-bootstrap service and grants developer access to it, the OS blueprint, and all visible Ryvn environments whose customer label exactly matches the customer slug. It adds the currently signed-in Ryvn user's email to policy membership, preserving existing grants and members. Environment names alone do not establish ownership. If multiple policies exist for the customer, consolidate them before retrying.

Install the Ryvn CLI and sign in with ryvn auth login using your Percepta organization account before registering. Registration reads identity and labels from Ryvn; policy changes take effect after the infra PR is merged and synced.

The command reads customerSlug from .blueberry/manifest.json, opens or updates an infra PR that writes ryvn/definitions/<customer>/blueprints/<customer>-os.blueprint.yaml, and does not create environment installations. The bootstrap service definition is copied from deploy/access-control/ryvn/access-control.service.yaml into ryvn/definitions/<customer>/services/<repo>-access-control-bootstrap.service.yaml. Rerunning preserves existing blueprint deployments and service settings on main while adding any missing registration or access grants. It authenticates with GITHUB_TOKEN, GH_TOKEN, or the GitHub CLI's gh auth token.

After adding a webapp, register it in that customer OS blueprint:

pnpm mosaic infra register-app my-app

App registration uses the same customer policy and adds an explicit developer grant for the app service, the tagged environments, and the registering user.

This opens or updates an infra PR that registers the app service, adds the app to the customer OS blueprint's app_databases default, and adds the app's server installation to the customer OS blueprint. The generated installation wires runtime environment variables at the Ryvn installation level, consumes the customer OS Postgres outputs with Ryvn valueFromOutput, references Mosaic blueprint outputs from supported Ryvn templates, and keeps the Helm config focused on chart knobs such as replicas, service, probes, resources, and ingress. Merge the OS blueprint PR before registering apps.

First release order

1. Run pnpm mosaic infra register-os-blueprint, then merge its infra PR and wait for the Ryvn sync. This registers the OS blueprint and bootstrap service.
2. Add a webapp with pnpm mosaic add webapp my-app, then run pnpm mosaic infra register-app my-app. Merge that infra PR and wait for its Ryvn sync to register the app service and deployment.
3. Push or rerun the app repository's release checks. The release workflows look up their service in Ryvn before building, so checks started before registration finishes need to be rerun.

For repos created before the bootstrap naming fix, set metadata.name in deploy/access-control/ryvn/access-control.service.yaml and service_name in .github/workflows/access-control-bootstrap-ryvn-release.yaml to <repo>-access-control-bootstrap, then rerun register-os-blueprint.

Development

Building the CLI

pnpm build

Testing locally

pnpm create:local --cwd /tmp --name test-app --yes --skip-install

From the repo root, the same script can be run with a filter:

pnpm --filter @percepta/create create:local --cwd /tmp --name test-app --yes --skip-install

Publishing

Publishing is automated via changesets on merge to main. See the repo-root .changeset/README.md and .github/workflows/build-and-publish.yml.

Add an agent to an existing webapp

npx @percepta/create add agent support-assistant --app my-app

Run inside a Blueberry monorepo. The app can be a directory name or scoped package name. Omit --app to pick from the monorepo's webapps, with the current app selected by default when running inside one. Interactive runs also prompt for missing agent names. Automation can use --non-interactive, --cwd, and --skip-install.

The command generates an editable Mastra agent definition, a protected Next.js POST endpoint, and shared @percepta/ai/agents runtime wiring for LiteLLM, Langfuse, and Percepta logging. V1 is stateless and has a five-step / 60-second execution limit. Existing files are never overwritten. The shared runtime is reused for subsequent agents.

The default local Docker Compose stack includes LiteLLM and Langfuse, following Langfuse's documented setup. Older Blueberry monorepos receive missing stack services and config when adding an agent. Run pnpm run setup, then sign in to Langfuse at http://localhost:3002 with [email protected] / mosaic-local-password. Supply a provider key via ~/.config/percepta/create.env, root .env, or shell; no gateway or tracing setup is needed for the generated development defaults.

Before deploying, run pnpm dlx @percepta/create@latest infra register-app my-app, including for an already-registered app. Registration detects generated agents and wires the deployed Mosaic URLs, an app-specific LiteLLM virtual key, and Langfuse project keys through secret environment bindings. Merge the resulting infra PR and roll out the OS blueprint. The target Mosaic installation must provide the AI service outputs and have LiteLLM and Langfuse enabled. The deployed model defaults to claude-sonnet-4-6; <app_name>_agent_model overrides it per environment and also scopes the app's gateway key.

Requires Node 24 for generated webapps. Local Docker fixture credentials must not be used in deployed environments. No persistent memory, background jobs, or chat UI is generated.