{
  "markdown": "---\ntitle: Applied Practical Thinking\nversion: v2\nstatus: candidate\naudience: developer\nvisibility: public\nsource: manual\n---\n# Applied Practical Thinking\n\nAPT is a monorepo for the Applied Practical Thinking platform.\n\n## Current repo shape\n\n```text\napps/\n  web/       # Public Vite + React application\n  worker/    # Cloudflare Worker API/AI subsystem\npackages/\n  ui/        # Shared APT presentational primitives\n  config/    # Shared token/config contracts\n  knowledge/ # Shared content/domain/assistant contracts\ndocs/        # Internal project/process documentation\n```\n\nAuthored site content and design docs live under `apps/web/`. Shared package contracts live under `packages/`.\n\n## Documentation model\n\n- `README.md` is the repo entrypoint and operating overview\n- `docs/` contains internal engineering, deployment, maintenance, workflow, and agent-facing repo docs\n- `apps/web/content/` contains authored external/public content that renders on the site\n- `apps/web/docs/design/` contains external-first design doctrine and public design reference docs\n- `apps/web/docs/design/` uses a 2-zone source model:\n  - `versions/v*/` authored canonical doctrine versions\n  - `static/` authored static support docs/contracts (review bundle, lint contracts, token JSON, instructions/reference)\n  - `tokens.json` is generated compatibility output from canonical `static/APT-TOKENS-CONTRACT.json`\n- Documentation architecture standard is defined in `apps/web/docs/design/versions/v2/APT-DESIGN-ARCHITECTURE.md` (Documentation Architecture section)\n- internal design support docs may live alongside the design doctrine source, but are not automatically public\n- `apps/web/public/` is generated runtime output only:\n  - `apps/web/public/content/`\n  - `apps/web/public/docs/`\n  - `apps/web/public/data/`\n\nCurrent-state vs target-state docs architecture:\n- Current-state canonical public docs source: `apps/web/docs/design/`\n- Target-state canonical public docs source (planned): `apps/docs`\n- Current pass is definition-first; no `apps/docs` structure migration is active yet\n\nDo not edit copied markdown under `apps/web/public/` as authored source.\n\nSafe edit flow for design docs:\n1. Edit `apps/web/docs/design/versions/v*/...` for doctrine changes or `apps/web/docs/design/static/...` for static support docs.\n2. Run `pnpm --dir apps/web run verify-doc-governance`.\n3. Run `pnpm --dir apps/web run copy-content-to-public`.\n\n## Getting started\n\nPrerequisites:\n\n- Node.js 20+\n- `pnpm`\n\nInstall dependencies:\n\n```sh\npnpm install\n```\n\nRun the web app:\n\n```sh\npnpm dev\n```\n\nRun the worker:\n\n```sh\npnpm dev:worker\n```\n\nBuild the web app:\n\n```sh\npnpm build\n```\n\nRun tests:\n\n```sh\npnpm test\n```\n\nYou can also run each app directly from its workspace:\n\n```sh\npnpm --dir apps/web dev\npnpm --dir apps/web build\npnpm --dir apps/worker dev\n```\n\n## Deployment model\n\n- `apps/web` is built by Cloudflare Pages from GitHub repo updates\n- `apps/worker` is deployed separately via Wrangler / `.github/workflows/worker.yml`\n- frontend public content/doc requests use the separate Worker origin from `VITE_API_BASE`\n- worker public content/doc normalization uses `PUBLIC_SITE_ORIGIN` to read Pages-hosted assets\n\nFor this reason:\n- `VITE_API_BASE` should exist in the Cloudflare Pages environment for the web project\n- the web app also supports a runtime override via `window.__APT_RUNTIME_CONFIG__.workerApiBase`\n- worker API base must be explicit in production (no implicit host fallback)\n- `PUBLIC_SITE_ORIGIN` must exist in the Worker runtime environment\n- GitHub Desktop pushes source changes only; Cloudflare Pages is what builds the frontend deploy\n- web CI/Pages builds run a prebuild guard (`apps/web/scripts/verify-worker-api-config.cjs`) that warns on missing/invalid `VITE_API_BASE`\n- if missing at runtime, the web app falls back to the known production worker base (`https://applied-practical-thinking.apt-account.workers.dev`)\n\nProduction values:\n\n- `VITE_API_BASE=https://applied-practical-thinking.apt-account.workers.dev`\n- `PUBLIC_SITE_ORIGIN=https://appliedpracticalthinking.com`\n\nCloudflare setup reminder:\n- Set `VITE_API_BASE` in **Cloudflare Pages > Settings > Environment variables** for both **Production** and **Preview**.\n- Then redeploy the Pages frontend after Worker deployment/config updates.\n\n### Labs/Proof/Insights data split (worker-first)\n\n- Web (`apps/web`) is the rendering layer: tabs, cards, filters, and detail presentation.\n- Worker (`apps/worker`) is the BFF assembly layer for public feeds and detail payloads.\n- Canonical public feed endpoints:\n  - `/api/feed/labs`\n  - `/api/feed/proof`\n  - `/api/feed/insights`\n  - `/api/feed/:feed/:idOrSlug`\n- Worker composes those feeds from static index assets and returns normalized contracts from `@apt/knowledge` (`PublicFeedItem`, `PublicFeedDetailResponse`).\n- Web should prefer feed hooks/services for Labs/Proof/Insights (`useFeedQueries.ts`) over client-side multi-index composition.\n\n## APT Principles Sync (Canonical to Public)\n\n`apt-principles-agents` is the canonical source for the public APT Principles content shown in this site. This repo is the public consumer and deploy target.\n\nRefresh flow after canonical updates:\n\n```sh\npnpm --dir apps/web run generate-apt-principles-agents-public\npnpm --dir apps/web run validation-report\npnpm --dir apps/web run build-content-index\npnpm --dir apps/web run copy-content-to-public\n```\n\nCommit regenerated artifacts:\n\n- `apps/web/public/docs/apt/**`\n- `apps/web/data/generated/aptPrinciplesPublicManifest.ts`\n\nOptional source override (for non-default local paths):\n\n```sh\nAPT_PRINCIPLES_AGENTS_ROOT=../apt-principles-agents pnpm --dir apps/web run generate-apt-principles-agents-public\n```\n\nPowerShell form:\n\n```powershell\n$env:APT_PRINCIPLES_AGENTS_ROOT=\"../apt-principles-agents\"\npnpm --dir apps/web run generate-apt-principles-agents-public\n```\n\nDeploy note:\n\n- Cloudflare Pages typically builds this repo only. In that context, the generator may log:\n  - `apt-principles-agents source not found; reusing committed public docs artifacts`\n- That warning is expected when committed generated artifacts are present and current.\n- If canonical refresh is required in CI, run builds in an environment where `apt-principles-agents` is checked out (or provide `APT_PRINCIPLES_AGENTS_ROOT`).\n\nCanonical runbook location: `apt-principles-agents/examples/workflows/apt-principles-agents-public-sync-flow.md`.\n\n## Content and design guardrails\n\n- Source content lives in `apps/web/content/` and authored registries live in `apps/web/data/`\n- Source design doctrine lives in `apps/web/docs/design/`\n- Internal repo/operator guidance lives in `docs/`\n- Shared APT primitives live in `packages/ui/` and are re-exported through `apps/web/components/apt/` during the migration\n- Shared TypeScript token contracts live in `packages/config/`\n- Shared content/domain contracts live in `packages/knowledge/`\n- `apps/web/public/` is output-oriented:\n  - copied markdown/docs/indexes are generated artifacts\n  - authored markdown/docs should not be edited in `public/`\n- Use semantic design tokens only; avoid raw color classes in app components\n\n## References\n\n- [APT Design Architecture](apps/web/docs/design/versions/v2/APT-DESIGN-ARCHITECTURE.md)\n- [APT Documentation Architecture (Compatibility Shim)](apps/web/docs/design/versions/v2/APT-ARCHITECTURE-DOC.md)\n- [APT Design System](apps/web/docs/design/versions/v2/APT-DESIGN-SYSTEM.md)\n- [Decision Log](docs/DECISION_LOG.md)\n- [Documentation Index](DOCUMENTATION_INDEX.md)\n",
  "bytes": 7531,
  "sha": "f9ef21737a0ea5a89f7a24b68d8db68cb507c1c22825b4bd771ed269e54a97d2",
  "repo_slug": "adthomps/applied-practical-thinking",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_adthomps_applied_practical_thinking_apt__c7ccd411/readme"
}