# FreeAppStore / FreeGameStore — AI agent guide

Drop this file's URL into your AI tool of choice (Claude Code, Cursor, Copilot, Aider, Codex, Windsurf, …) and the agent will know how to build apps and games for the platform.

**Add this line** to your tool's project context (e.g. `CLAUDE.md`, `.cursorrules`, `AGENT.md`, `.aider.conf.yml`, etc.):

```
Read https://raw.githubusercontent.com/freeappstore-online/ops/main/SKILLS.md for FreeAppStore platform guidance.
```

---

## What the platform is

Two storefronts, one shared backend + tooling.

|  | FreeAppStore | FreeGameStore |
|---|---|---|
| Domain | freeappstore.online | freegamestore.online |
| GitHub org | freeappstore-online | freegamestore-online |
| CLI | `fas` (`@freeappstore/cli` on npm) | `fas --store games` (a games-first `fgs` is in the works) |
| Templates | `template-standalone`, `template-connected` | `template-game-canvas`, `template-game-grid`, `template-game-3d` |
| Storefront repo | `freeappstore-online/freeappstore` | `freegamestore-online/freegamestore` |

Apps and games published on these stores are **always free**, **open source under MIT**, **track nothing**, and **work in any modern browser**.

## Your job as an AI agent

When a user says "help me build a free app/game on this platform":

1. **Install + auth** the CLI (one-time):
   ```
   npm i -g @freeappstore/cli
   fas login
   ```
2. **Scaffold:** `fas init <app-id>` (or `--template game-canvas|game-grid|game-3d` for a game).
3. **Write code** in `web/src/App.tsx` and supporting files. The template ships a `Shell` layout, brand fonts, CSS variables, and a PWA manifest — use them.
4. **Run `fas check`** before publishing. It enforces the brand and privacy rules below.
5. **`fas publish`** (add `--store games` for a game). Provisions the GitHub repo, Cloudflare Pages project, DNS, custom subdomain, and storefront entry in one call.
6. **`git push upstream main`** — auto-deploys via Cloudflare Pages in ~30 seconds. Future commits to `main` deploy automatically.

## What you must NOT do

- **Don't add tracking, analytics, cookies, or any third-party scripts** beyond Google Fonts. The compliance check will block publish.
- **Don't override the brand CSS tokens** (`--paper`, `--ink`, `--accent`, `--line`, `--line-strong`, `--panel`, `--muted`) outside `web/src/index.css`. Apps look consistent across the storefront — that's mandated.
- **Don't add custom display fonts** beyond Manrope (body) + Fraunces (display) and system fallbacks. Game *canvas* contents can use any pixel-fonts; this rule is for DOM/HTML text only.
- **Don't ask the user for Cloudflare or GitHub tokens.** Provisioning happens through the admin worker over the platform session — never raw tokens.
- **Don't deploy manually with `wrangler pages deploy`.** Pushes to `main` auto-deploy. Manual deploys are a one-way ticket to drift.
- **Don't create staging environments or feature branches** for deployable changes. The platform is trunk-based: push to main, fix forward.

## Required tech stack

- TypeScript ^5.7, React ^19, Vite ^6, Tailwind CSS ^4.1, pnpm
- Node >= 22
- 3D games: Three.js + React Three Fiber (`@react-three/fiber` + `drei`) — already wired in `template-game-3d`

The scaffolds set all of this up; don't change major-version pins without a reason.

## Brand mandates (enforced by `fas check`)

- **Fonts:** Manrope (body) + Fraunces (display, 700-800). Both must be referenced from `web/index.html` and used in CSS.
- **CSS tokens:** Use `var(--accent)`, `var(--ink)`, `var(--paper)`, etc. Don't redefine outside the canonical theme file.
- **Layout:** Desktop sidebar (17rem) + main. Mobile: header + main + dock. The `Shell` component handles this.
- **Dark mode:** `prefers-color-scheme: dark` (auto). Don't ship your own theme switcher.
- **Border radius:** 1.25rem cards, 0.75rem buttons.

## Privacy mandates

- Zero analytics, tracking, cookies, fingerprinting.
- Per-user data goes in `localStorage` (standalone) or via the platform SDK's KV (connected).
- The only allowed third-party domain is `fonts.googleapis.com` / `fonts.gstatic.com`.

## Compliance checks the platform enforces

The `fas check` command (and the per-app GitHub Action) runs:

1. **No template placeholders** — every `APPNAME` substituted.
2. **No tracking SDKs** — none of 8 known trackers (Google Analytics, Plausible, Mixpanel, Hotjar, PostHog, Segment, Amplitude, GTag).
3. **Brand fonts present** — Manrope and Fraunces both referenced.
4. **No brand overrides** — no app redefines a platform CSS token outside the canonical theme file; no non-brand `font-family` declarations in DOM CSS.
5. **No scroll (games only)** — games must fit the viewport. No `overflow: scroll/auto` or `min-height: 100vh` on `html` / `body`. Detected by the `@freeappstore/games` dep. Use `<GameShell>` from that package; it's the canonical viewport lock.
6. **PWA manifest** — `web/public/manifest.json` with `name`, `display`, `start_url`.
7. **Bundle size** — main chunk under 300 KB gzipped.

`fas publish` runs these as a gate. Override with `--skip-checks` only if you really must — admin review will catch it.

## Game-specific UI primitives

Games on FreeGameStore use **`@freeappstore/games`** for layout + topbar:

```tsx
import { GameShell, GameTopbar } from '@freeappstore/games';

export default function App() {
  return (
    <GameShell topbar={<GameTopbar title="Tetris" score={42} />}>
      {/* your canvas / game DOM */}
    </GameShell>
  );
}
```

- `<GameShell>` hard-locks the layout to `100svh` and prevents overflow at every level — no document scroll, ever.
- `<GameTopbar>` is the **only** allowed topbar shape. Pass `score` for the simple case, or `stats={[…]}` for games that show level / lives / time.
- Both honor the platform CSS tokens. Don't pass custom colors.

## How deployment works

```
git push upstream main → GitHub Actions OR CF Pages integration → live in ~30s
```

No manual deploy. No staging. No portal. Just push.

`fas publish` is **provision-once** (creates the repo + hosting). After the initial publish, every subsequent change is just `git push`.

## File layout in any scaffolded app

```
my-app/
├── package.json           (root workspace)
├── pnpm-workspace.yaml
├── LICENSE                (MIT — required)
├── .github/workflows/compliance.yml
└── web/
    ├── package.json
    ├── index.html         (links Manrope + Fraunces, sets PWA meta)
    ├── vite.config.ts
    ├── public/manifest.json
    └── src/
        ├── main.tsx
        ├── index.css      (Tailwind + brand CSS vars)
        ├── App.tsx        (← where you write the app)
        └── components/Shell.tsx  (the brand layout)
```

## Useful URLs

- Apps storefront: https://freeappstore.online
- Games storefront: https://freegamestore.online
- Apps creator guide: https://freeappstore.online/contribute.html
- Games creator guide: https://freegamestore.online/contribute.html
- CLI source + npm: `@freeappstore/cli` (https://github.com/freeappstore-online/sdk/tree/main/packages/cli)
- Compliance source: `@freeappstore/compliance` (https://github.com/freeappstore-online/sdk/tree/main/packages/compliance)
- Platform API: https://api.freeappstore.online (`/v1/audit`, `/v1/uptime`, `/v1/apps/mine`)

## TL;DR for the agent

> The user wants to build a free, MIT-licensed, no-tracking app/game. Use `@freeappstore/cli`. Scaffold with `fas init`, write code, run `fas check`, run `fas publish`, push to main. Don't add trackers, don't override brand tokens, don't ask for cloud credentials. The platform handles hosting and DNS automatically.