> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/conventions.md). # CONVENTIONS.md ## Guiding Principles * Optimize for readability over cleverness. * Document what exists before describing planned behavior. * Keep hackathon-specific work clearly scoped to its extension/demo surface. * Prefer existing project patterns over new abstractions. * Validate commands and paths before documenting them. ## Naming * AI OS is the host application and platform identity. * Trend Finder is a repo-local extension inside AI OS, not the whole project. * `ai-os` is the canonical package/runtime/storage prefix for new global identifiers. * `findtrend` is a legacy hackathon-era name. Do not add new global `findtrend` identifiers. * Preserve existing `VITE_CLAUDE_OS_*` and `FINDTREND_*` env names as compatibility contracts unless a migration explicitly adds aliases, docs, and tests. * Use descriptive names for functions, files, and data models. * Booleans read as questions: `isActive`, `hasSignal`, `shouldRefresh`. * Functions describe actions: `calculateTrendScore`, `normalizeSourceItem`, `loadTrendReport`. * Match product language by boundary: AI OS for host/operator cockpit behavior; Trend Finder terms like trend, source, evidence, score, creator angle, and watchlist for the extension. ## Files & Structure * Route files live in `src/routes/`. * Shared UI components live in `src/components/`. * Radix-based local primitives live in `src/components/ui/`. * Shared client utilities live in `src/lib/`. * Bun scripts live in `scripts/`. * Static and generated-safe assets live in `src/assets/`. * Generated private runtime data stays out of git. ## TypeScript / React * Use TypeScript for application and script code. * Keep route components close to their route file when behavior is route-specific. * Use React Query for runtime data that is fetched from local middleware. * Use existing `@/` path aliases. ## Styling * Use the existing Tailwind CSS 4 and local component conventions. * Keep dashboard UI dense, scannable, and operational. * Avoid changing imported UI primitives unless needed by the task. ## Data * `src/data/live-data.example.json` is the committed fallback shape. * `src/data/live-data.json` is generated, local, and gitignored. * New Trend Finder extension data models should distinguish raw source items, normalized evidence, topic clusters, scores, and report output. ## Secrets * Do not commit `.env`, `.env.local`, generated private data, or API keys. * Use placeholders shorter than real key patterns in docs. * Keep `.githooks/pre-commit` active with `git config --local core.hooksPath .githooks`. ## Testing * Test behavior, not implementation details. * Add focused tests when scoring, normalization, or source parsing becomes non-trivial. * Tests stay close to the behavior they cover: source utilities under `src/lib/__tests__/`, route tests under `src/routes/__tests__/`, component and hook tests under their local `__tests__/` folders, script tests under `scripts/lib/__tests__/` or extension test folders, and browser flows under `tests/e2e/`. * Use `bun run test` to run all tests, `bun run test:watch` for watch mode. ## Git & Version Control * Commit messages should be concise and imperative. * Keep commits scoped to one logical change. * Branch names should use `type/short-description`, such as `docs/baseline` or `feat/trend-scoring`. ## Local Dev Tools | Category | Tool | Config | | --------------- | ----------------------------------- | ----------------------------------------------------------------------- | | Package Manager | Bun 1.3.14 | `.bun-version`, `bun.lock` | | Dev Server | bun run dev (Vite / TanStack Start) | `vite.config.ts` | | Formatter | Prettier | `.prettierrc` | | Linter | ESLint | `eslint.config.js` | | Type Safety | TypeScript (app) | `tsconfig.json` | | Type Safety | TypeScript (scripts) | `tsconfig.scripts.json` | | Testing | Vitest | `vitest.config.ts` | | Testing | Playwright (chromium + pages-demo) | `playwright.config.ts` | | Observability | pino | `src/lib/logger.ts`, `logs/.gitignore` | | Git Hooks | Pre-commit secret scan | `.githooks/pre-commit` | | Database | N/A (no app database) | No DB service, migration config, ORM dependency, or DB env key detected | | Deployment | Cloudflare Worker style entry | `wrangler.jsonc`, `src/server.ts` | ## CI/CD | Bundle | Status | Workflow | | ------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Code Quality | configured | .github/workflows/quality.yml (Lint, Format Check, Type Check, Script Type Check) | | Build & Test | configured | .github/workflows/quality.yml (Tests, Coverage, Browser Tests, Build) | | Bundle Budget | configured | .github/workflows/quality.yml (Bundle Budget, runs after Build) | | Security | configured | .github/workflows/security.yml (Dependency Audit, Secret Scan via gitleaks, CodeQL SAST, Dependency Review) | | Integration | configured | .github/workflows/integration.yml (Production Build, E2E Integration; PR-only gate) | | Operations | configured | .github/workflows/deploy.yml (Quality Gate, Cloudflare Workers Deploy, Smoke Test, Failure Notification), .github/workflows/release.yml (GitHub Release on version tags), .github/dependabot.yml (weekly Bun + GitHub Actions updates) | ## Infrastructure | Component | Provider | Details | | ---------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- | | CDN/DNS | Cloudflare | Via wrangler.jsonc Workers deployment | | Hosting | Cloudflare Workers | TanStack Start SSR, entry: src/server.ts | | Health | /health endpoint | Worker-level, pre-SSR, returns JSON status + timestamp | | WAF | Cloudflare (manual) | Enable OWASP Core Ruleset in Cloudflare dashboard | | Rate Limit | In-worker | Token-bucket, 60 req/min per IP, src/lib/rate-limit.ts | | Security Headers | In-worker | X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy | | Backup | N/A | No database or persistent state | | Deploy | GitHub Actions + Cloudflare Workers | .github/workflows/deploy.yml deploys on main or manual dispatch; rollback procedure in docs/deployment.md | | Local Dev | bun run dev / bun run worker:preview | Vite on 127.0.0.1:5189 for UI; Wrangler preview on 127.0.0.1:8788 for `/health` and rate-limit validation | ## Media Policy See `docs/media-policy.md` for full asset guidelines. * Maximum 200 KB per non-logo committed asset in `src/assets/`; AI Rogue music tracks use the reviewed 900 KB cap in `docs/media-policy.md` * Prefer WebP for photos, SVG for icons * Run `bash scripts/check-asset-sizes.sh` before committing new assets * All meaningful images require descriptive `alt` text ## When In Doubt * Read the current file before editing. * Prefer smaller, accurate docs over broad speculative docs. * Separate current starter behavior, AI OS host behavior, and Trend Finder extension behavior. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/conventions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.