{"id":50019953,"url":"https://github.com/aotter/mantle-starters","last_synced_at":"2026-06-14T13:01:47.578Z","repository":{"id":356932108,"uuid":"1234414541","full_name":"aotter/mantle-starters","owner":"aotter","description":"AotterMantle public starters, themes, and GitHub-release scaffolder.","archived":false,"fork":false,"pushed_at":"2026-05-20T08:01:08.000Z","size":413,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"develop","last_synced_at":"2026-05-20T08:54:58.558Z","etag":null,"topics":["agents-md","ai-agent","clam-cms","cloudflare-workers","cms","mcp","monorepo","scaffolder","starter-template","template","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/aotter/mantle-starters#readme","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aotter.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-10T06:38:45.000Z","updated_at":"2026-05-20T06:24:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aotter/mantle-starters","commit_stats":null,"previous_names":["aotterclam/clam-cms-starter-publication","aotterclam/clam-cms-starters","aotterclam/mantle-starters","aotter/mantle-starters"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/aotter/mantle-starters","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aotter%2Fmantle-starters","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aotter%2Fmantle-starters/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aotter%2Fmantle-starters/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aotter%2Fmantle-starters/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aotter","download_url":"https://codeload.github.com/aotter/mantle-starters/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aotter%2Fmantle-starters/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33423286,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"online","status_checked_at":"2026-05-24T02:00:06.296Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents-md","ai-agent","clam-cms","cloudflare-workers","cms","mcp","monorepo","scaffolder","starter-template","template","typescript"],"created_at":"2026-05-20T07:18:48.405Z","updated_at":"2026-06-14T13:01:47.572Z","avatar_url":"https://github.com/aotter.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mantle-starters\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)\n\nPublic monorepo of mantle starter templates.\n\nThis repo is consumed by the `create-mantle` scaffolder tarball attached\nto each GitHub release. End users usually should not clone this repo\ndirectly: they start from\nthe Mantle landing page, paste the\ngenerated prompt into Claude Code / Cursor / Codex, and the install Skill\nin [`aotter/mantle`](https://github.com/aotter/mantle) invokes\nthe release tarball. The scaffolder downloads a tagged tarball of this\nrepo, merges `_common/` + `\u003carchetype\u003e/` + optional theme overlays into\nthe user's empty directory, then initializes their own Git repo.\n\nPremium / per-customer starters live in the private sibling\n[`aotter/mantle-starters-premium`](https://github.com/aotter/mantle-starters-premium).\nThat repo mirrors `_common/`; sync strategy is TBD.\n\n## How to install\n\nRecommended path:\n\n1. Open the Mantle landing page.\n2. Pick an archetype, optional theme, and optional feature overlays.\n3. Paste the generated prompt into Claude Code / Cursor / Codex.\n\nThat route runs the [`mantle` install Skill](https://github.com/aotter/mantle/tree/develop/skills/install), which interviews the user for brand, locales, audience, and deployment intent before invoking the scaffolder.\n\n### Direct scaffolder call\n\nThe agent-driven flow (paste the landing prompt into Claude Code /\nCursor / Codex) is the recommended path because the install Skill\ninterviews the user for brand / locales / audience before running the\ncommand. If you're already past the interview or testing this repo and want to invoke the\nscaffolder directly, the command shape is:\n\n```bash\nnpx https://github.com/aotter/mantle-starters/releases/download/v0.0.11-alpha.17/aotter-create-mantle.tgz \u003carchetype\u003e \\\n  --project-name \"\u003cmy-site\u003e\" \\\n  --brand \"\u003cMy Brand\u003e\" \\\n  --description \"\u003cone-line site description\u003e\" \\\n  --locales \"en,zh-TW\" \\\n  --github-owner \"\u003cyour-github-login\u003e\" \\\n  --summary \"\u003cinstall-moment marker\u003e\"\n  # optional: --theme \u003ctheme\u003e     (l4-minimal-ink | l4-editorial-warm | l4-editorial-journal | l4-playful-pop)\n  # optional: --feature \u003cfeature\u003e (repeat or comma-separate; e.g. contact, customer-account)\n```\n\nUse a versioned release URL while Mantle is on alpha prereleases. GitHub's\n`/releases/latest/` endpoint ignores prereleases, so it returns 404 when\nthere is no stable release yet.\n\n`\u003carchetype\u003e` is one of: `presence`, `publication`, `intake`,\n`transaction`, `blank`. The CLI fetches `sources.json` at runtime,\ndownloads the matching starter tarball, merges `_common/` +\n`\u003carchetype\u003e/` + selected feature overlays + optional `themes/\u003ctheme\u003e/`,\nfills `{{BRAND}}` / `{{LOCALES}}` / `{{DESCRIPTION}}` placeholders,\nruns `git init` + `pnpm install`, and prints RUN_NOTES JSON. After it\nreturns, `cd \u003cmy-site\u003e` and follow that directory's own README for the\nlocal-dev Quickstart.\n\nFor SDK/runtime internals, release policy, and agent skills, go back to\n[`aotter/mantle`](https://github.com/aotter/mantle). This repo is\nonly the starter source and scaffolder implementation.\n\n## Layout\n\n```\nmantle-starters/\n├── _common/                   ← shared backbone, merged into every install\n│   ├── AGENTS.md.template     ← cross-tool agent entry\n│   ├── mantle/\n│   │   └── site.md.template   ← Mantle's semantic layer\n│   └── .gitignore.template\n├── presence/                  ← landing-page / brand-presence starter\n├── publication/               ← owner-published-content starter\n├── intake/                    ← publication + structured `leads` Schema\n├── transaction/               ← small catalog + cart + order workflow\n├── reservation/               ← roadmap note; routes to intake for v0.1\n├── community/                 ← roadmap placeholder\n├── membership/                ← roadmap placeholder\n├── blank/                     ← headless API + MCP starter\n├── themes/                    ← theme overlays (artist-designed; v0.0.9+)\n└── sources.json               ← archetype + feature + theme dispatch\n```\n\nEach archetype has its own top-level directory, but `_common/` is the\nshared backbone. The pattern is intentionally shadcn-like: common\nprimitives and workflow scripts live once, while each archetype keeps\nits domain-specific composition readable and forkable.\n\n## Provisioning Backbone\n\nEvery active archetype receives the shared `_common/scripts/provision.mjs`\nrunner during scaffolding and exposes:\n\n```bash\npnpm run provision:plan\npnpm run provision:up\n```\n\nThe shared flow keeps the user's first Cloudflare deploy dashboard-led:\nthe agent pushes the repo, the user creates a Worker from GitHub, and\nCloudflare auto-provisions id-less D1/KV/R2 bindings. After the first\ndeploy, the coding agent runs `pnpm exec wrangler login` and\n`provision:up` to write non-secret config and Worker secrets. Do not\nfork this flow per archetype unless the archetype needs an explicit\nfeature provision step under `scripts/.mantle-provision.mjs`.\n\n## Source map (`sources.json`)\n\n`sources.json` at the repo root is the authoritative dispatch from\narchetype / feature / theme key → source directory.\n`create-mantle` fetches it at runtime\n(`raw.githubusercontent.com/aotter/mantle-starters/\u003cref\u003e/sources.json`)\non every install. Adding an archetype, feature, or theme = update this\nfile; no SDK publish is needed unless merge logic changes.\n\n## Install merge order\n\nFor each install, `create-mantle` extracts files in this order\n(later files overwrite earlier files on conflict):\n\n1. `_common/\u003cfile\u003e` → `\u003cfile\u003e` (`.template` suffix stripped)\n2. `\u003carchetype\u003e/\u003cfile\u003e` → `\u003cfile\u003e`\n3. Selected feature overlays, in dependency order\n4. Each theme overlay listed in the request, in order\n\nThen `{{PLACEHOLDER}}` macros are substituted across the result. See\n[`aotter/mantle` ADR-0016](https://github.com/aotter/mantle/blob/develop/docs/adr/0016-site-semantic-layer.md)\nfor the macro list.\n\n## Adding a starter\n\n1. Create a new top-level directory in this repo (e.g. `membership/`).\n2. Add the starter sources. Keep the directory standalone — no\n   `workspace:*` deps; pin `@aotter/mantle-*` to the published\n   version that this starter ships against.\n3. Add a corresponding entry to `sources.json` under `archetypes:`.\n   Runtime fetch picks it up on the next install — no\n   `create-mantle` republish required unless merge logic changes.\n\n## Starter Lockfiles\n\nEvery starter carries its own standalone `pnpm-lock.yaml` because\n`create-mantle` scaffolds a new consumer project outside this monorepo.\nDo not regenerate those lockfiles from inside the workspace; workspace\ncatalog resolution can hide stale standalone locks.\n\nWhen changing starter dependencies, the root catalog, or any\n`@aotter/mantle*` version, run:\n\n```bash\npnpm refresh:starter-locks\n```\n\nThat script scaffolds each archetype into a temp directory, resolves the\nlockfile as a standalone project, then copies the generated lockfile back\nto the starter directory. CI runs the same flow in check mode:\n\n```bash\npnpm check:starter-locks\n```\n\nIf this check fails, do not hand-edit `pnpm-lock.yaml`; run the refresh\nscript and commit the resulting lockfile changes.\n\n## Adding a theme\n\n1. Create a new directory under `themes/\u003ckey\u003e/` (e.g.\n   `themes/l4-minimal-ink/`).\n2. Add `src/theme/tokens.ts` and any optional component/template\n   overrides. The theme only contains files that go *under* `src/theme/`\n   — not a full starter scaffold.\n3. Add a corresponding entry to `sources.json` under `themes:`.\n\n## Per-starter testing\n\nEach subdirectory is a standalone project. Inside it:\n\n```bash\npnpm install\npnpm validate\npnpm typecheck\npnpm dev\n```\n\n`pnpm dev` runs the starter's safe Wrangler wrapper: it binds to\n`localhost:8787`, keeps inspector port selection out of the way, and\nstores Wrangler HOME/XDG/log/state files under project-local ignored\ndirectories.\nUse `localhost`, not `127.0.0.1`, in browser URLs and OAuth app settings so\ncookies, callbacks, and local onboarding state all share the same origin.\n\nThe root CI runs the workspace checks across starters and the\nscaffolder, but each starter remains a standalone consumer project.\nRuntime code lives upstream in the `aotter/mantle` packages; this\nrepo only pins and consumes those published packages.\n\n## License\n\n[MIT](./LICENSE) — see each starter for its own LICENSE if\npresent.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faotter%2Fmantle-starters","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faotter%2Fmantle-starters","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faotter%2Fmantle-starters/lists"}