knowledge.oriz.in

Open Knowledge Format bundle. 859 concept files. source · RSS · llms.txt

decision (265)

Userscript creation flow: prototype in Tweeks, port to portable .user.js — USerscript prototyping via Tweeks at tweeks.io that generates per-site JS from plain English) as a fast in-browser PROTOTYPE. If the result is keepable, copy the generated JS, port to a proper Tampermonkey-format .user.js with a metadata block (@name, @namespace, @version, @match, @grant, @updateURL pointing at GitHub raw), commit to chirag127/userscripts monorepo, cross-publish to Greasefork + OpenUserJS. This gets AI generation speed PLUS portable + auditable + versionable artifacts without vendor lock-in.
Alternative free-forever backup channels for GitHub code and metadata — Alternative free backup channels for GH protection repositories and their metadata (issues, PRs, wikis, releases) using Cloudflare R2, Backblaze B2, Hugging Face Datasets, and the native GitHub Migration API. Integrated into our overall disaster recovery options.
Alternative free-forever backup channels for GitHub code and metadata — Alternative free backup channels repositories and their metadata (issues, PRs, wikis, releases) using Cloudflare R2, Backblaze B2, Hugging Face Datasets (with caveats), and the native GitHub Migration API. Integrated into our overall disaster recovery options.
Workspace layout: repos///// — 5-level hierarchy: owner, own/forks, 4 buckets, category, repo
Shipping a forked extension to Chrome Web Store under our name — GPL-3.0 forks to CWS: keep license, note modified, rename
Private repos are excluded from the 9-host mirror cron — Mirror cron excludes private repos via isPrivate + name list
Tweeks (NextByte) modification — personal mods OK, no public redistribution — Tweeks: closed-source, personal use only, no redistribution
Secrets workflow: sops+age primary, Doppler ALONGSIDE for runtime sync (hybrid) — Sops+age source of truth. Doppler parallel CI sync only
Fleet cut 2026-07-01 — drop gocode, Codeep, Claurst, Coddy — Reduce coding-agent fleet from 10 → 6. Remove marginal agents (gocode, Codeep, Claurst, Coddy) after audit found no differentiating usage patterns.
OSS audit — file real gaps as upstream issues (2026-07-01) — Systematic audit of every OSS tool we depend on. 60+ issues + comments + PRs filed across 29 upstream repos in one session. Filing at upstream, never patching locally, is the family default.
Blog strategy 2026-07-01 — one source, multi-target cross-posting — Canonical blog format (Markdown+frontmatter) + list of platforms + API-driven cross-posting workflow
Pipeline stack lock 2026-07-01 — pnpm + MegaLinter + Dagger TS — The five-layer canonical stack for every oriz repo: pnpm 11 (package + tasks), MegaLinter (lint), Dagger TS (CI pipelines), TypeScript everywhere. No mise, no super-linter, no Earthly, no Python for new scripts.
freellmapi: run from source, auto-pull on boot, free-tier aggregator — Run `tashfeenahmed/freellmapi` (14K-star OpenAI-compat proxy stacking 16 free LLM provider tiers) from the local fork's dev server. Auto-start on Windows login on ports :3001 (server) + :5173 (Vite client).
OmniRoute: run from source via dev server, auto-pull on boot — Switch from `npm install -g omniroute` to running the cloned fork's dev server. Auto-start on Windows login pulls upstream and launches pnpm dev in a dedicated Windows Terminal tab.
Add Gemini CLI to oriz coding-agent fleet — 11th interactive agent. Free tier via Google OAuth. 1,000 req/day + 60 req/min. Headless scripting flag, no public REST API. No card-on-file. Grill-locked 2026-06-30.
Zero-cost inference backends — Ollama + Cloudflare Workers AI + Puter.js — Approved LLM endpoints when not using paid Claude/GPT keys. Local (Ollama) + serverless (Workers AI) + browser (Puter.js). Zero card, zero subscription. Grill-locked 2026-06-30 alongside gemini-cli-agent-addition.
Hono framework — write once, deploy to all 4 serverless rails — Every API/Worker uses Hono. Same logic writes once, deploys everywhere \ logic compiles to CF Workers, Deno Deploy, AWS Lambda, and Render Node \u2014\ \ via 4 thin adapter shims (~10 LOC each). Removes per-rail rewrites when failover\ \ requires switching rails."
Modal Labs for GPU batch + Val.town for utility scripts — Modal Labs + Val Town for specialized compute (verified). Modal handles GPU-heavy batch jobs ($30/mo recurring credits = ~50 T4-hours, no card at signup, hard Workspace budget cap). Val.town handles utility scripts + webhook receivers + cron reminders (100K runs/day free, GitHub OAuth signup). Modal is NOT part of the 4-rail HTTP fallback chain; it's a specialized rail.
Journal photo pipeline — 4-host replicate-everywhere — Journal uploads photos to four free hosts in parallel + ImageKit + imgbb + GitHub Releases) with client-side WebP compression, sha256-dedup on GH Releases, and first-200-wins HEAD race on read. Replaces the legacy Firebase Storage single-host path.
Cloudflare Web Analytics on every public surface — single SITE_TAG family-wide — Single CF Web Analytics token shared family-wide covers ALL family domains: the 26 apps on CF Pages, the 19 APIs'' docs/HTML landing pages on GitHub Pages, and any package/book/skill landing page. APIs JSON-only responses are NOT instrumented (no HTML to beacon). Single site_tag family-wide per Rule 15 (shared-tenant-by-default); apps separated via the CF Web Analytics ''Hostname'' filter.
Feature flags — deferred (YAGNI) until first real need — No feature flags in family every concrete need we have today is solved by something else (tier checks via Firebase Auth claims for Pro/Max gating; git push for incident response; A/B testing has no users yet). Adding a flag system would be infra we''d maintain to solve problems we don''t have. Trigger to revisit: first real incident where a runtime kill-switch would have helped, OR first product decision that needs per-user A/B.
No separate dev/prod projects — one prod + emulator + 5 cheap defensive moves — No separate dev/prod projects fan-out): a separate dev Firebase project is net-negative at oriz scale today\ (Spark plan, no paying users, solo founder, mostly stub apps). Emulator + one\ prod + 5 cheap pre-emptive moves (GCP lien, defineSecret(), wrangler env split,\ 1Password CLI, CF Tunnel for Razorpay webhooks) is right-sized. Triggers to flip\ and add `oriz-dev`: first ₹99 live payment, second deploy-rights human, or\ first prod-data incident — whichever comes first. Razorpay structurally forbids\ a second staging account (one business-PAN per merchant).
Public image-upload tool on image.oriz.in — gated by free/pro tier — Locked 2026-06-23. oriz-pixie gets public /upload page using the 5-host replicate pipeline (Cloudinary + ImageKit + imgbb + freeimage\ + GH Releases). Free tier: 5 uploads/day, requires sign-in + reCAPTCHA v3. Pro\ tier: unlimited. Reuses lib/photos.ts from oriz-roam-journal-app. Durability promise:\ best-effort only, no SLA — free tier compliance limits guarantees. Anonymous\ users see paywall card.
Flat subdomain pattern: .oriz.in for every public-facing repo — Flat <slug>.oriz.in for every public repo, ~85 total
Monetization centralized on oriz.in — Razorpay checkout only on oriz.in/pricing, apps redirect
Subdomains — category-based with path routing per tool — Per-tool subdomains abandoned. Tools at category.oriz.in/tool for SEO
All apps static — no SSR — All 6 apps static Astro builds. CF Pages SSR deprecation does not affect us
Eleven saturated apps archived 2026-06-25 — 11 saturated-market apps archived. Subdomains freed. Repos read-only
Finance — one repo, ten routes at finance.oriz.in — 10 finance calculators into single repo. Shared @oriz/finance package
agent-skills monorepo + symlinks — chirag127/agent-skills single truth for skills. Symlinked into agent skill dirs
Build-gate: top-3 Google results must have a defect — Build tool only when top-3 Google results have real defect
Own/frk split — two buckets on top of flat repos/ — Repos split into repos/own/ (originals) and repos/frk/ (forks)
openmodel-shim-api deleted 2026-06-25 — openmodel-shim-api deleted. Kept freellmapi + omniroute only
Polyrepo with category consolidation — Polyrepo, one repo per category. Tools share repo as routes
Submodules for single-clone fleet — Git submodules for single clone. OK under 50 submodules
Frontend default stack — Astro + React islands + Tailwind + shadcn/ui — Default stack: Astro + React + Tailwind + shadcn/ui. Per-repo design pass sets palette, typography, signature
Default stack: Astro + React + Tailwind + shadcn — Default stack: Astro + React + Tailwind + shadcn/ui. React over Preact
frontend-design skill pass per repo — Each repo gets frontend-design pass for per-repo palette on shared baseline
Analytics stack: no card, no self-host — GA4 + CF Analytics + Clarity + PostHog + Fathom + GoatCounter
Backup: Restic→B2 nightly + Windows built-in monthly — Nightly Restic to B2 for files, monthly Windows Backup for disk
Disk image backups — Windows built-in Backup-and-Restore — Windows Backup-and-Restore replaces Macrium for disk images
Umbrella repo — chirag127/oriz as the single clone entrypoint — Umbrella repo entrypoint: one clone pulls entire fleet
Workspace layout — flat repos// with type-suffix sort — Flat repos/<slug>/ dir, type in suffix, forks via .is-fork file
Donations only — no Pro tier, no ads, no Razorpay checkout — Donations only: BuyMeACoffee, GH Sponsors, UPI
Donations only — no Pro, no ads — Donations only, no Pro, no ads, Razorpay killed
No auth in apps or APIs — login is a separate project — Apps/APIs 100% public, login redirects to dedicated login-manager
Brand-independent repo naming — drop oriz- prefix 2026-07-02 — All chirag127/* repos use descriptive names without brand prefix. Enables future brand/domain migration without repo renames. Only npm package scope will migrate separately (deferred).
chirag127 owns everything — oriz-org dissolved 2026-07-02 — Every repo (own, forks, workflows, umbrella) lives under chirag127. oriz-org GitHub org is dissolved. Secrets consolidated in the umbrella (chirag127/workspace).
Hybrid Dagger+GHA architecture locked — 2026-07-02 — Per-class Dagger modules in chirag127/workflows. GHA = 5-line adapter. Tauri Windows = GHA host for cargo, Dagger for portable parts. Both cacheVolume() + actions/cache.
MCP toolbox allowlist + audit 2026-07-02 — Blessed MCP server allowlist grouped by purpose plus audit notes flagging duplicates, health-check candidates, and removal candidates.
Reusable workflows layered with Dagger — 2026-07-02 — chirag127/oriz-workflows publishes reusable GH Actions workflows per repo class. Each workflow calls `dagger call` — the actual logic lives in Dagger TS modules. Downstream repos are 5-line pins.
SAP hyperspace docs crawl — deferred to interactive SSO — Crawl of SAP corp AI-proxy docs + internal GHE profile blocked by MS Entra SSO; requires user's live browser session.
Workspace-owns-secrets model 2026-07-02 — chirag127/workspace umbrella holds ALL deploy secrets. Per-repo CI runs public-only (lint/test/build). Deploy triggered via repository_dispatch after CI green.
Scope-cut reversed — all 99 archived repos back in fleet 2026-07-02 — Reverses scope-cut-2026-06-25. Every archived repo unarchived and returns to the maintained fleet. Fleet now = 119 (20 active + 99 revived). Maintenance level: alive (Dependabot + working CI), not full-feature reactivation.
Dagger keep + full sweep — confirmed 2026-07-02 — After a re-grill on Dagger's disadvantages (Docker dep, cold start, ecosystem loss), the 2026-07-01 pipeline-stack decision is confirmed. Full retro-migration of all 20 own/* repos proceeds. Local pipeline runs justify Dagger over `act`.
LangChain ecosystem — deferred, revisit 2026-10-02 — LangChain / LangGraph / LangSmith / integrations. Not adopted, not rejected. Current MCP + skills + AGENTS.md stack covers the same surface. Revisit in 3 months if real gaps surface.
Skills in .agents/skills/ workspace-scoped + junctions for all 5 agents — Canonical skills dir .agents/skills/, NTFS junctions, 5 agents
Public-only multi-Git mirror + auto-start services + datasets-to-build queue — Mirror chirag127 to 4-5 Git hosts. Auto-start Hr/RTK/cavemem. Ship datasets as static APIs
Mirror repos/own/* to 9 popular GitHub alternatives — weekly cron from the umbrella repo — Mirror repos/own/* to 9 free Git hosts via GH Actions
Hosting migration: Cloudflare Pages -> GitHub Pages + analytics-everywhere stack — CF Pages abandoned for GH Pages, CF DNS retained, analytics everywhere
GitHub repo naming best practices — consolidated rules for the family — Single source for all naming rules v5+v6+best practices
Naming policy v6 — family brand + product brand + category + suffix — Repos: oriz-<product>-<category>-<suffix>. Forks exempt
Repo naming locked: -site for every site + role suffix matrix for everything else — Naming suffixes per repo type (-site, -bs-ext, -vsc-ext, -cli, -mcp)
Chrome contract — @chirag127/astro-chrome v0.1 — 4 per-site config files drive generic components, 3-level contract \ sidebar (Section \u2192 Group \u2192 Leaf); shared Datasheet Dark tokens across\ \ every site (no per-site accent); Iosevka wordmark stamp (slug-only, no ORIZ prefix);\ \ 24 auto-generated legal pages; pnpm workspace at the workspace umbrella root."
Content apps scope — tabs / journal / lore-summaries, ship after Wave 1 — Three Wave 3 content apps. tabs-cards-app at tabs.oriz.in cards, Notion/Tabby style). roam-journal-app at journal.oriz.in (networked daily journal, Roam-style backlinks). lore-book-summaries-app at lore.oriz.in (book + movie + show summaries). All three: anonymous-first, free + sponsor footer. Ship after janaushdhi + ncert + blog land.
cs-me-app scope — personal canon at me.oriz.in / cs.oriz.in — Personal site at me.oriz.in (aliased cs.oriz.in to same site) Maximal personal canon: resume + project portfolio + writing + contact + reading\ log + music + books-read + photo dump + movies/watch list. Pulls from knowledge/\ where possible. Wider scope than a classic dev personal site — treat as the\ user's personal everything-page.
home-app shape — marketing landing, 5-section grid, not a dashboard — oriz.in marketing landing page. Single hero + 5-section grid linking to /apps, /tools, /books, /packages, /me. Minimal copy. Designed for first impression and discovery. NOT a logged-in dashboard, NOT a personal home, NOT a status overview.
janaushdhi-app scope — daily Jan Aushadhi scrape, substitutes, stores, savings — janaushdhi.oriz.in scrapes Janaushadhi Pariyojana \ product portfolio daily via GH Action, commits CSV + JSON snapshots, renders per-product\ \ price-history graphs, brand \u2192 generic substitute finder, per-state store\ \ locator, and savings calculator. Free + sponsor footer ONLY \u2014 public health\ \ ethics forbid ads, affiliate, third-party tracking."
ncert-app scope — merge per-chapter NCERT PDFs into one-per-book, all classes, EN + HI — ncert.oriz.in catalogs all NCERT textbooks (Pre-Primary + 1-12) \ all subjects, English + Hindi. Daily GH Action URL-merges per-chapter PDFs from\ \ ncert.nic.in into one PDF per book using qpdf/pdftk, publishes as GH Release artefacts\ \ (NOT CF Pages \u2014 25MB limit). Catalog UI shows class/subject grid \u2192 download\ \ links."
omni-post-app shape — admin dashboard for the omni-publish package — omni-post.oriz.in wraps @chirag127/omni-publish with admin dashboard. /admin shows the pending GH Issues drafts queue, cross-post history per platform, retry-per-platform controls, and edit-before-publish UI. Public root (/) is a read-only 'where I post' catalog. /admin is Firebase Auth + admin-email allowlist gated.
Per-app contents specification — sidebar + pages + CI/CD — Every app follows contents spec. 4-config structure split (site/nav/sidebar/footer) lives in src/config/. Common pages (landing, about, changelog, admin) + per-tool pages + 24 legal pages from astro-chrome. CI/CD via reusable workflow from astro-shell-npm-pkg + separate test.yml.
Q3 2026 ship order — home + janaushdhi + ncert + blog first, then 16 tools, books in parallel — Q3 2026 ship order. Home, janaushdhi, ncert, blog FIRST. 16 tool subdomains. 5 books
Drafts queue host — private GitHub repo with Issues (replaces Telegram) — Drafts queue lives in private GitHub repo chirag127/oriz-drafts using GitHub Issues. omni-publish creates one issue per draft per platform with platform-labelled tags. Issue body is ready-to-paste copy + canonical URL + cover image URL. Close issue when manually posted; reopen if retry needed. Replaces Telegram (banned in India). Requires OMNI_DRAFTS_GH_PAT env var with repo scope.
GitHub Pages as canonical static JSON API host — Static read-only JSON APIs via GitHub Pages in name-api repos Pages with a custom subdomain. GH Actions cron updates the JSON. Cloudflare Worker only for dynamic / write / auth-gated endpoints. APIs are publishable to RapidAPI + other monetization marketplaces.
Market-data APIs — FII/DII Activity + Tickertape MMI as standalone repos (GH Actions + GH Pages) — Two India-market data APIs, each in own GitHub repo oriz-flow-fii-dii-activity-api (NSE/Moneycontrol FII/DII net activity) + oriz-mmi-tickertape-mmi-api (Tickertape Market Mood Index). GH Actions cron scrapes; GH Pages + raw.githubusercontent.com serve. The earlier CF Worker design (and the briefly-tried oriz-market-data aggregator) were both reverted on 2026-06-22; this file is now active again under the per-repo + GH-Pages shape.'
Blog cross-post strategy — daily post, omni-publish fan-out, GH Issues drafts (not Telegram) — pages-blog-app posts daily to blog.oriz.in. omni-publish fans out \ out automatically to dev.to + Hashnode + Bluesky + Mastodon + Threads. Drafts\ \ for manual channels (X, Reddit, LinkedIn, Medium) queue to GitHub Issues in private\ \ chirag127/oriz-drafts repo \u2014 NOT Telegram (banned in India). Per-channel\ \ AI rewrite via NVIDIA NIM primary + OpenRouter fallback. Canonical URL = oriz.in\ \ on every channel for SEO."
Book publish pipeline — Markua .md → 5 channels via @chirag127/oriz-book-build + omni-publish — Books written as Markua Markdown and published via pipeline (Leanpub-compatible), built by the new @chirag127/oriz-book-build npm package\ (17th family package) which wraps Pandoc to emit EPUB3 + PDF + MOBI artefacts.\ omni-publish takes those artefacts and fans out to 5 channels: Leanpub (Markua\ git push, 80% royalty) + Draft2Digital aggregator (manual upload, documented)\ + Gumroad (API auto, 10%) + LemonSqueezy (API auto, 5%+50\xA2 MoR) + Amazon KDP\ (browser-uploader bot, no API). Plus Google Play Books Partner Center (manual\ upload, ISBN-recommended). 5 first books locked, all brand-first naming. Prose\ licensed CC-BY-NC-ND 4.0 + code samples MIT.
books.oriz.in shape — static catalog, Oriz Me drafts first, others outlines — books.oriz.in static catalog showing cover + price + buy-links per book. First book to draft fully: Oriz Me (PWYW $9, personal essays, biographical). Other 4 (Oriz Stack, Oriz Paisa, Oriz PDF, Oriz Janaushdhi) get chapter outlines initially. Per-book channels per book-publish-pipeline. Substack is the newsletter platform; free chapter drops via Substack.
Per-runtime framework matrix locked — Astro 6 for sites, Vite+React+WXT for extensions extensions; esbuild+TS for VS Code extensions; tsup+Node 22 for CLIs and MCP servers. Each runtime gets the framework that ships best to its target.
PWABuilder is the primary PWA→native converter; Tauri optional — PWABuilder primary PWA converter for Astro apps Microsoft-hosted, CLI available) converts the PWA into Android AAB + Windows MSIX without per-app native code. Tauri stays available as opt-in for apps that want auto-update + smaller binaries. iOS is PWA-only (no Apple Developer Program, no test devices). Bubblewrap, Capacitor, Cordova all rejected.
Mirror every chirag127/oriz* repo to 4 git hosts weekly — Friday-4am cron mirrors submodules to 4 hosts
MIT license on all 41 chirag127/oriz* repos — MIT license across all repos \ to MIT on 2026-06-21. Unlocks every free-for-OSS perk (Sentry for OSS, Crowdin\ \ for OSS, BrowserStack OSS, FOSSA, etc.) and clarifies commercial use is fine \u2014\ \ the family still monetises via ads/affiliate/subscription, that's orthogonal to\ \ the source license."
Family deploy architecture — DNS, gating, releases, dashboards — Per-app GH Actions: main to prod, PR to preview, tags to APK/EXE
Weekly release train — Wednesday 9 AM IST, CalVer per app, hot-fix bypass, git-cliff changelog — Weekly release train Wed 9 AM IST workspace-level cron that tags + releases each app that has commits since its last tag. Versioning is CalVer per app (v2026.06.21). Hot-fixes bypass the train via [hotfix] in the commit message, triggering an immediate tag + deploy. Changelogs auto-generated by git-cliff from conventional commits.
@chirag127/omni-publish package — auto-blog releases to 8+ platforms — @chirag127/omni-publish handles auto-publishing releases notes / blog posts to dev.to + hashnode + medium + X + LinkedIn + Bluesky + Mastodon\ + Reddit on tag push or release create. Triggered by GitHub Actions reusable workflow\ per repo. Platforms are env-gated — if DEVTO_API_KEY isn't set globally,\ dev.to is skipped automatically. Lives alongside the existing oriz-omni-post-app\ (the orchestrator UI / catalog of cross-posts).
omni-publish v0.1.2 follow-ups (deferred from v0.1.1) — 5 follow-ups deferred from omni-publish v0.1.1 v0.1.2: per-repo per-day rate-limit cache (high), retry on transient 5xx (medium),\ compile TS → dist/ for non-bundler consumers (medium), Hashnode tag _id resolution\ (low), Threads single-user-token assumption validation (low).
packages.oriz.in shape — auto-discovery Starlight catalog with showcase pages — packages.oriz.in auto-discovery Starlight catalog lists every chirag127/*-npm-pkg repo, fetches README + version + bundle metadata, and renders per-package showcase pages with live demo iframe, copy-paste install snippet, badge wall, and StackBlitz playground link. Rebuilds daily via cron + on tag push from any package repo.
Dual-location package surfacing — oriz.in overview + packages.oriz.in catalog — Packages surfaced on oriz.in/apps + packages.oriz.in /packages + /mobile + /desktop + /extensions overview with cards per app + store/channel badges (Play Store, Microsoft Store, Chrome Web Store, etc.) with ''Coming soon'' for unreleased channels; (2) packages.oriz.in is a standalone Astro Starlight catalog that auto-discovers every chirag127/*-npm-pkg repo and renders the full README + npm/GH/bundlephobia metadata per package. Channels metadata lives in home-app/src/data/apps.ts (manual) + auto-discovery from GitHub Releases for native installer URLs.'
Newsletter on Substack — single family newsletter, free tier, 10% if paid — Single family newsletter at chirag127.substack.com (or brand-aligned name). Free tier; Substack takes 10% if a paid tier ever ships. ONE newsletter, NOT per-app. Daily blog feed + weekly digest + book drop announcements. Embed signup form on home-app + every content app footer. Replaces the earlier Buttondown + EmailOctopus split.
Tools shape + priority — 16 single-purpose subdomains, locked ship order — 16 tool apps, each at own *.oriz.in subdomain pixie, grid, forge, shift, dice, cipher, paper, vitals, rank, reel, echo, pivot + remainder). Anonymous-first auth. Free + opt-in sponsor footer. Affiliate allowed only where ethically clean (Amazon book links on scribe-text; NOT on health tools). Locked ship priority for Wave 2.
Revenue channels 2026 — every product fans out to every viable channel via omni-publish — Revenue channels across 26 apps + 17 packages + 5 books + future browser-/VS-Code-extensions + CLIs + MCP servers) auto-publishes\ to as many revenue channels as 2026's API reality allows. Orchestrated by @chirag127/omni-publish\ on every tag push. AI copy via NVIDIA NIM primary + OpenRouter free-models fallback.\ Drafts for manual-only platforms (X, Reddit, LinkedIn, Medium — all dead/closed\ APIs in 2026) land in a single Telegram channel split into 4 sections. Rate-limit\ ceiling: 1 auto-post per channel per day per repo.
Headroom 0.27 via Docker — chain Hr ? hai ? Bedrock — Hr 0.27 native build blocked by ASR. Docker bypasses. Backend anthropic passthrough
MCP server registry — 11 servers installed 2026-06-27 — Final MCP set after audit. Searxng, github Docker, npx/uvx tools, chirag127 toolbox
Personal notes in public repo — discipline-only — Obsidian vault in public repo, discipline not tooling
Family-wide /privacy page on oriz.in — Locked 2026-06-20: single canonical /privacy on oriz.in
i18n — English-only today, Weblate Hosted Libre when ready — English-only until non-English demand; then Weblate
Family-wide naming policy — repo, npm, subdomain — GitHub slug = npm name. Subdomains shorter. Suffix every repo
Cross-post engine package is named oriz-omnipost — RSS cross-poster named @chirag127/oriz-omnipost
Brand capitalisation — Title-Case 'Oriz' in user-facing copy — Title-Case Oriz user-facing; lowercase oriz-* in code
cards-site — all financial cards, India — cards-site (cards.oriz.in) covers all financial cards in India market: credit + debit + forex + prepaid + travel. Inspired by CardInsider / TechnoFino / Paisabazaar / BookMyForex. Reviews + comparisons + calculators + guides + offers + tools. Affiliate-monetisable.
Family-wide /stats page on oriz.in (auto-tracked, public, all 11 sites + all repos) — oriz.in/stats aggregates visitor data from all family sites sites + code-stats data from all family repos, build-time fetched from CF Web Analytics + GitHub Insights + Wakatime + Tokei. Public, transparent, auto-refreshed via daily cron. Reinforces the auto-only-tracking and auto-tracking-everywhere posture. Single oriz-kit component pulls everything.'
Lifestream auto-event sources — three streams (GitHub webhooks + Wakatime daily + CF Web Analytics daily) — Three auto-sources feed oriz-me JSONL lifestream \ auto-tracked event sources only \u2014 GitHub webhooks via Hookdeck, Wakatime\ \ daily-summary cron, and Cloudflare Web Analytics daily-summary cron. No manual\ \ entry, no minute-grain coding capture, no per-pageview visitor capture. Reinforces\ \ the auto-only-tracking rule."
oriz-me-site stays a single site with sections — not split into now/uses/gear/cv subdomains — me.oriz.in single Astro site, not split /gear, /reading, /coding, /lifestream, /cv, /contact). Not split into now.oriz.in, uses.oriz.in, gear.oriz.in, etc.
AI split — Puter.js (browser) + Cloudflare Workers AI (server) — Two AI providers picked by surface. Puter.js for browser, CF Workers AI for server (user-pays, no API key client-side). Cloudflare Workers AI for server-side calls inside the Hono Worker (10K neurons/day, zero-egress, native binding). Different surfaces, different reasons.
API mocks — MSW (in-process) + Mockoon (out-of-process), split by surface — Two API-mock tools. MSW handles in-browser + in-Node test mocks (unit / Vitest, component stories, Playwright dev). Mockoon handles E2E + manual dev mocks of third-party APIs (Razorpay sandbox, Open-Meteo, Alpha Vantage when offline). Both free OSS. Different surfaces, different reasons.
Cloudflare Worker quota mitigation playbook — 8-step playbook for staying under CF Workers free tier free-tier quota (100K req/day per Worker, 10ms CPU/req). Cache aggressively at the edge, split Workers by domain, and prefer `_headers`/`_redirects` over Worker logic when possible. Generalises the URL-shortener cache trick to every Worker in the family.'
Cron split — Cloudflare Cron Triggers + GitHub Actions schedule, by job shape — Cron on both substrates. CF Triggers for low-latency, GH Actions for heavy jobs; GH Actions schedule for build / publish jobs that need a runner. Pick by the job's shape, not by convenience.
Data APIs — Open-Meteo (weather) + Alpha Vantage (finance) — Open-Meteo for weather, Alpha Vantage for finance / market data. Both free, no card. Both fronted by the umbrella Hono Worker with KV-backed cache (1h TTL on weather, 1d TTL on finance EOD) per the CF Worker quota mitigation playbook.'
Distribution + queues locked: 3-store browser-ext + dual VS Code marketplace + PWA-only + CF Queues + Hookdeck — Batch 13 lock covering distribution + reliability \ publish to Chrome + Firefox + Edge. VS Code extensions publish to VS Code Marketplace\ \ + Open VSX (JetBrains walked back). Every site is a PWA via @vite-pwa/astro (Capacitor\ \ + Tauri walked back). Webhook reliability is Hookdeck \u2192 Cloudflare Queues\ \ (Trigger.dev walked back). All free, no card."
Health checks — split between healthchecks.io (cron heartbeats) and Better Stack (HTTP uptime) — Cron-job liveness verified by healthchecks.io \ heartbeat pings (dead-man-switch on 20 free checks), HTTP endpoint uptime is verified\ \ by Better Stack monitors (10 free monitors). Two distinct surfaces, two free tools,\ \ no overlap. Reinforces the auto-only-tracking rule \u2014 both verify auto-tracked\ \ surfaces without human polling."
Hono RPC for type-safe API client — Type-safe site to API client via Hono. No codegen \ no schema files \u2014 backend types flow to N frontends through a workspace package."
One Hono Worker at api.oriz.in is the entire API layer — All 11+ sites and extensions share single Hono Worker at api.oriz.in, NOT per-site Pages Functions.
Local dev tunneling — Wrangler + Astro dev + Cloudflare Tunnel — Local dev runs on three substrates via CF Tunnel \ picked by surface \u2014 Wrangler dev for Cloudflare Workers, Astro dev for sites,\ \ Cloudflare Tunnel (cloudflared) for exposing localhost to the public internet\ \ for webhook testing. ngrok and localtunnel REJECTED."
Queue — Cloudflare Queues, picked for stack cohesion — Cloudflare Queues primary durable queue. Picked for native Worker bindings + same-account billing surface, not for feature richness. Upstash QStash + Inngest documented as deferred alternatives.
Each extension gets a rich website, not a small landing page — Per-extension full marketing/docs/changelog/support sites
Markdown-in-repo only — no headless CMS, anywhere — Content as .md/.mdx in-repo, no CMS CMS, TinaCMS, Strapi, Sanity, Contentful, Storyblok and every other headless CMS are explicitly REJECTED.
RSS-driven cross-post engine — oriz-omnipost — @chirag127/post-site fans RSS posts to other platforms new entry out to every blogging platform that exposes a public API. Adapter pattern; idempotent; canonical URL preserved; short-link fallback when the target truncates content.
Keep extensions.oriz.in catalog AS WELL AS per-extension subdomains — Central catalog + per-extension subdomains
Three-format feed publishing — RSS 2.0 + Atom 1.0 + JSON Feed — Every content site publishes RSS, Atom, JSON feeds 2.0, source-of-truth for oriz-omnipost), /atom.xml (Atom 1.0), /feed.json (JSON Feed v1.1). oriz-kit ships <FeedDiscovery /> + generators.'
Forms — trio (Web3Forms primary + Static Forms fallback + Tally for rich) — Vendor-redundant contact forms: Web3Forms + backup' primary, Static Forms fallback, both browser-only, both free unlimited). Tally handles rich / multi-step / conditional forms. Three roles, no overlap.
journal-site — best features of all five journal apps — journal.oriz.in mines best features of Day One, Bear Notion, Obsidian, and Logseq into one journaling experience. Big scope chosen knowingly; flagship-grade polish target.
Lifestream federation — mirror to BOTH AT Protocol and ActivityPub — oriz-me JSONL canonical, AT Protocol mirror under me.oriz.in.atproto AND ActivityPub outbox at me.oriz.in/activitypub/outbox. Single source, two protocols.
Newsletter split — Buttondown for technical, EmailOctopus for marketing — Two newsletter senders. Buttondown technical, EmailOctopus marketing / dev audience (Markdown + API). EmailOctopus handles general marketing (visual editor, larger free tier).
oriz-home portal also lists extensions — oriz.in home shows extensions catalog section for cross-promo
Each extension has its own /privacy page; family boilerplate at oriz.in/privacy-base — Per-extension /privacy. Boilerplate at oriz.in/privacy-base
Each Chrome extension gets its own subdomain on oriz.in — Each extension gets dedicated *.oriz.in subdomain + catalog slot
Build cache — GitHub Actions cache + pnpm CAS (3-layer strategy) — Three-layer build cache: pnpm, GH Actions cache' global store dedupes deps cross-repo locally. Layer 2: GitHub Actions cache (10\ GB/repo free) keyed by pnpm-lock.yaml hash + Astro build cache keyed by source\ hash. Layer 3: Turbo Remote Cache + Bazel REJECTED — Vercel signup + card\ / overengineering.
Add Neon Postgres as the relational tier of the DB stack — Neon Postgres added as relational DB. Free plan \ no card, scale-to-zero, branching for previews. Sits alongside Firestore (documents/auth),\ \ Turso libSQL (warm cache), and JSONL canonical (archive) \u2014 the 4-tier DB\ \ stack is now picked-by-shape."
DB admin — console-only, no desktop DB tool — Every DB administered through vendor browser console only \ console (Firebase Console, Neon Console) or its first-party CLI (Turso CLI, libSQL\ \ CLI). NO desktop DB tool \u2014 Drizzle Studio / Outerbase / Beekeeper Studio\ \ / TablePlus all REJECTED. Zero install footprint, every team member can access\ \ via browser, no per-user license."
firebase-rest-firestore (NOT firebase-admin) for Workers compatibility — Hono Worker uses firebase-rest-firestore (REST + service-account) JWT). The firebase-admin SDK is excluded because workerd only partially supports gRPC.
Object storage split — GitHub Releases for binaries, Backblaze B2 for blobs; Cloudflare R2 rejected — Versioned binaries in GitHub Releases. Unversioned blobs elsewhere Backblaze B2. Cloudflare R2 is rejected because adjacent paid features pull in a card-on-file requirement.
Image CDN — chained 3-tier fallback (Cloudflare Images → wsrv.nl → ImageKit) — Every image goes through oriz-kit Image wrapper with fallback chain resolves through a 3-tier fallback: Cloudflare Images first, wsrv.nl on 5xx, ImageKit on 5xx.
Linkroll — Raindrop.io is source of truth, blog.oriz.in/links built at deploy time — Family linkroll lives in public Raindrop.io collection blog.oriz.in/links is built at deploy time from the Raindrop REST API. Cached via the Cloudflare edge with a 1-hour TTL on the build artifact; nightly cron re-deploys to surface new links.
Multi-engine 'Search the web' button on every family site — Every site ships single Search the web button button (in the header or footer) that opens a popover with multiple search engines. Component lives in @chirag127/oriz-kit as <MultiSearch />.
OG card generation — Satori on api.oriz.in/og + ray.so for code — Non-code posts get OG cards from Satori on Hono Worker route at api.oriz.in/og. Code-heavy posts continue on ray.so. Static-cached via CF edge cache headers, no per-post PNGs in any site repo.
Sidebar — 4 tiers based on site shape — Sidebar via @chirag127/sidebar, 4-tier config differs by site type. Four tiers: A) auto-generated for tools, B) curated TOC for longform, C) browse + search for catalogs, D) family directory for the brand hub.
Status banner on every site — Dismissible <StatusBanner /> from oriz-kit on every site that consumes Better Stack's RSS incident feed; visible only when an incident is live, with severity + link to status.oriz.in.
Knowledge bundle depth scales with folder size, ceiling 5 — Folder depth adaptive: flat for tiny, 5 levels for big
Analytics — 5-tier stack (CFWA + GA4 + PostHog + Clarity + UTM) — Five analytics layers in parallel on every site \ \u2014 Cloudflare Web Analytics (raw load), Google Analytics 4 (marketing funnel),\ \ PostHog (product + session replay + flags), Microsoft Clarity (heatmaps + Microsoft-side\ \ session replay), UTM tracking (attribution convention). Each layer covered by\ \ an `ENABLE_<TOOL>` env-var kill-switch so no single quota pinch can break a site."
Auto-tracking everywhere — every family-wide metric is captured automatically — All metrics auto-tracked across oriz family \ is auto-captured. The oriz-me lifestream specifically pulls from auto sources\ \ only \u2014 GitHub commits via webhook, npm publishes via post-publish hook, VS\ \ Code coding sessions via Wakatime API, site visits via CF Web Analytics, builds\ \ via GH Actions webhook. No manual entry anywhere in the metric pipeline. Manual\ \ = decay; auto = honest."
Backups — restic CLI in GH Actions cron, target Backblaze B2 — Weekly encrypted restic backups to B2 via GH Actions Actions schedule, targeting a Backblaze B2 bucket. Locks the restic + B2 + GH Actions triple.
Bug tracker — GitHub Issues only — GitHub Issues only bug tracker across family \ repo uses its own GitHub Issues as the sole bug tracker. Linear, Trello, Jira,\ \ Plane.so, Asana, Height \u2014 all REJECTED. Cross-repo triage via repo:org searches.\ \ Free unlimited, GitHub-native, integrates with PRs and commits via
Code stats — every metric tool turned on (9-tool stack) — Code-stats across every public family repo \ stack \u2014 Sonarcloud + CodeRabbit + Codecov + CodeClimate + DeepSource + biome\ \ + GitHub Insights + Tokei + Lines-of-Code badge. All free for OSS. Auto-tracked\ \ per the auto-only-tracking rule. Extends the 5-tool code-quality decision with\ \ three more stat-shaped tools (GH Insights / Tokei / LoC badge) on top of the 5\ \ quality tools."
Geocoding — deferred (no current need); CF-IPCountry covers geo-routing today — No geocoding, deferred \ need address\u2194coordinate translation. Cloudflare's free `CF-IPCountry` request\ \ header covers all current geo-routing needs (consent banner geo, payment-route\ \ geo). When a site lands a map feature, the swap target is OpenStreetMap Nominatim\ \ or Mapbox \u2014 both free, no card."
Logs — Better Stack Logs (aggregation) + Cloudflare Workers Tail (live) — Two-layer logs: CF Workers Tail + Better Stack' (5-min retention, 0 cost, wrangler tail). Better Stack Logs for cross-Worker aggregation + alerts + searchable retention (3 GB/mo free, same vendor as our status page + uptime monitors). Quota math: ~30 MB/mo realistic load vs 3 GB/mo cap = ~100x headroom.
Notifications — FCM (transport) + Knock (orchestration) — Two-layer notifications: Knock + FCM' (in-app + email + SMS + web push); FCM stays as the web-push transport. Free 10K notifs/mo on Knock, free unlimited on FCM.
Perf monitoring — Vercel Speed Insights as RUM — Vercel Speed Insights for RUM Web Vitals site, complementing Cloudflare's edge-measured metrics and Sentry's API traces. Free, no Vercel hosting required.
Project management — GitHub Projects only — GitHub Projects for family-wide task management \ single GitHub Projects board on chirag127/oriz master, with kanban + table + roadmap\ \ views. Notion, Obsidian Tasks, Linear, ClickUp, Asana, Trello \u2014 all REJECTED.\ \ The knowledge/ OKF bundle covers documentation; GitHub Projects covers tasks."
SEO — three pillars: sitemap + IndexNow + JSON-LD — Three SEO pillars: sitemap, IndexNow, JSON-LD' IndexNow (instant indexing), and JSON-LD structured data (semantic). Submitted to Google Search Console + Bing Webmaster Tools. All free, all no-card.
Testing — three-layer stack (Vitest unit + Playwright E2E + Storybook+Chromatic visual) — Three-layer testing: Vitest, Playwright, Chromatic per PR' against Storybook in parallel. PR fails on any failure in any layer. All free, no card.
Time tracking — Wakatime ONLY (Toggl walked back) — Wakatime only time tracking ONLY. Wakatime auto-tracks coding time via IDE plugin (VS Code + JetBrains). Toggl Track was originally adopted alongside it for manual non-coding tracking, then walked back the same day under the new auto-only-tracking rule. Non-coding time is intentionally NOT tracked rather than manually tracked. File renamed via git mv from time-tracking-toggl-plus-wakatime.md.'
URL shortener three-tier free stack — s.oriz.in primary, TinyURL fallback, GitHub Gist redirect zero-infra — Three-tier URL shortener, all free, no card s.oriz.in CF Worker (primary, edge-cached 301s). Tier 2: TinyURL API (fallback, unlimited free, no auth, no card). Tier 3: GitHub Gist HTML meta-refresh redirect (zero-infra, last-resort). Quota math shows the family sits at ~1-2% of the CF Worker free envelope.
URL shortener quota mitigation — cache the 301 itself at the CF edge — s.oriz.in CF Worker, 100K req/day free tier script. We send `Cache-Control: public, max-age=31536000, immutable` on every\ 301 redirect so CF's edge caches the redirect itself; subsequent visitors hit\ the cache, not the Worker. With caching, only the first visitor per URL per edge\ POP per year burns a Worker request. Realistic upper bound at family-wide traffic\ is ~1-2K requests/day — well under 100K. No external shortener required.
UTM-only marketing attribution — UTM params for marketing attribution on outbound links links, captured by PostHog + Cloudflare Web Analytics. No paid attribution tool, no SaaS click-tracker, no bounce-redirect domain. oriz-kit ships <UtmLink> to enforce kebab-case naming.
Voice / SMS — deferred; route via Knock when needed — Voice/SMS deferred to Knock, no standalone provider \ on card-on-file grounds. If/when SMS becomes needed, the family routes it through\ \ Knock's bundled SMS channel \u2014 already locked as the multi-channel notification\ \ orchestrator (10K notifs/mo free)."
Image host — chained 4-tier origin (repo + ImgBB + Imgur + GitHub user-content) — 4-tier image host: CF Pages, imgbb, imgur, GH user content' → ImgBB → Imgur → GitHub user-content. Composes alongside the 3-tier\ image-CDN chain in the oriz-kit <Image> wrapper.
4-level hierarchy for big knowledge directories — services/, decisions/, glossary/ use 4-level paths
Code quality stack — Dependabot + biome + CodeRabbit + Sonarcloud — Code quality: Dependabot, biome, CodeRabbit, Sonarcloud. Free OSS
OKF v0.1 is the canonical format for all family knowledge — OKF v0.1 for all concept files in knowledge bundles
Per-repo CI workflows; master matrix only owns deploys — REVERSES master-matrix CI. Each repo owns its ci.yml
Accessibility — three-tool stack (axe + Pa11y + Lighthouse CI) — axe-core + Pa11y + Lighthouse CI per PR on any new a11y violation in any tool. Each tool catches a different category.
Code quality — 5-tool stack (Sonarcloud + CodeRabbit + Codecov + Code Climate + DeepSource) — Five code-quality tools per public repo \ tools. Sonarcloud (SAST + smells), CodeRabbit (LLM PR review), Codecov (coverage\ \ delta), Code Climate (A \u2014 F maintainability), DeepSource (autofix). All five\ \ free for the family's public / OSS repos. Builds on the earlier 4-tool stack \u2014\ \ adds Codecov + Code Climate + DeepSource alongside the existing Dependabot + biome\ \ + CodeRabbit + Sonarcloud."
Family stack lock — Astro 6 + React 19 islands + Tailwind v4 + pnpm + Biome — Same stack all sites. CF Pages monetised, GH Pages info-only
Tool categories roadmap — Tier 1 + Tier 2 + anti-list — 15 tool subdomains: 8 Tier 1 ship day 1' + 7 Tier 2 (stub day 1, fill in later). Tier 3 is explicitly skipped. Anti-list captures categories deliberately rejected (URL shorteners, AI image gen, etc.).
Tools shipped as 15 separate repos, one per subdomain — Each tool category = own GitHub repo deployed to its own Cloudflare Pages project at <category>.oriz.in. No tools-site monorepo. Picked over 'one repo, 15 subdomain builds' for portfolio framing and SEO concentration.
Family-wide design system locked: Oriz Datasheet Dark — Single dark design system: Oriz Datasheet Dark across all surfaces
Each Chrome extension is its own GitHub repo, added as a submodule — Each extension = own repo as git submodule
Cloudflare Pages hosts every website and app; no other host — All sites to Cloudflare Pages free. GH Pages backup only
Extension auth: Firebase primary, license-key fallback — Extensions: Firebase Auth + license-key fallback
Every extension publishes to Chrome + Firefox + Edge stores — Each extension: GH Actions publishes to Chrome, Firefox, Edge
Stay on Firebase Spark forever — never enable Blaze — Firebase capped to Spark. Blaze excluded (no-card rule)
Every site builds a static GitHub Pages mirror per §16 — Each site CI builds GH Pages fallback on push to main
Add Hookdeck for Razorpay webhook reliability — Hookdeck queues Razorpay webhooks. 100K/mo free
Monitor only oriz.in apex, not subdomains — SSL + uptime on apex only. Subdomains inherit via CF
Spaceship is the registrar; Cloudflare hosts DNS + email routing — Domains at Spaceship. NS to Cloudflare. Email Routing to Gmail
Custom-domain strategy is *.oriz.in subdomains — Every surface under *.oriz.in, never separate apex
AdSense apex application; Ezoic / Mediavine fallback — Single AdSense for oriz.in apex. Fallback: Ezoic, Mediavine
Support every viable payment method, geo-routed — Max payment methods: Razorpay, Lemon Squeezy, keygen.sh, 6 donations
No service in the stack may require a paid subscription — All external services must work free-tier indefinitely
ONE subscription unlocks every site and every extension — Single Razorpay sub in Firestore unlocks all paid features
Razorpay is the primary subscription provider — Razorpay primary billing. Stripe, Lemon Squeezy, Paddle fallbacks
Anti-bot — defense in depth (CF WAF + Turnstile + Hono rate-limit) — Bot defense: CF WAF + Turnstile + Hono rate-limit. All free
Captcha — Turnstile primary + hCaptcha fallback (both, regional auto-detect) — Turnstile primary, hCaptcha fallback. Single Captcha component
Consent management for many categories — Klaro config + GA4 Consent Mode v2 + geo routing + cookie-less default — Klaro consent: 5 categories. EU/UK denied, US/CA accepted
Cookie banner policy — none by default; Klaro lazy-loaded only for EU+tracker pages — No cookie banner default. Klaro only for EU/UK with trackers
Env keys + GH Actions secrets — single source of truth, two delivery tracks — Two-track env: public .env.example, private GH Secrets at org
Multi-provider auth — 6 providers on Firebase Auth, Apple deferred — Firebase Auth: 6 providers (Email, Google, GitHub, Anonymous, MS, Passkeys)
Doppler is the source of truth for secrets; GitHub / Cloudflare / Firebase are runtime mirrors — Doppler single source for secrets. GH/CF/Firebase synced downstream
Security headers — strict CSP via _headers + dual CI audit — Strict CSP/HSTS/Permissions-Policy via CF _headers from oriz-kit
Corp laptop vs personal laptop split (2026-06-29) — CC + Bedrock corp-only. Personal on free providers. No-card blocks CC paid on personal
Workspace canonical; globals derived by script (2026-06-29) — Workspace files canonical. Global configs derived via sync-globals.mjs. Drift triggers grill-me
OKF auto-lookup via UserPromptSubmit hook (CC) + manual script (other agents) — Fix for OKF-not-triggering symptom: a 50-LOC Python script scores knowledge/index.md lines by prompt-token overlap, returns top-3 paths. CC fires it automatically; other agents run it manually because their harnesses lack pre-prompt hooks.
claude-notifications-cli — deleted 2026-06-29 — CLI fork dropped. Notifications no longer fit 4-agent fleet
MCP config single source of truth across all 5 agents — Single .mcp.json synced to all 5 agents via script
Data lives in each app's own repo — no separate data repos for janaushdhi/ncert/financial-cards — Locked 2026-06-22. Reverses proposal to create separate data repos `oriz-*-data` repos for data-driven apps. Reason: ''I don''t want to increase the number of repositories just for the sake of it.'' Each app''s `data/` dir holds its own data. Per-app GH Action cron writes fresh data to that dir + commits. Push to app''s main branch triggers CF Pages redeploy automatically. Apps consume data via build-time import (static fastest). Where runtime freshness needed: lazy fetch + SWR + localStorage cache. Existing `oriz-flow-fii-dii-activity-api` + `oriz-mmi-tickertape-mmi-api` repos STAY (they''re API services, not data; data lives in their own data/ dir per-repo).
ncert.oriz.in app — combined PDF directory (scrape + merge + release) — ncert.nic.in only per-chapter PDFs. ncert.oriz.in combines them is to provide COMBINED whole-book PDFs that don't exist anywhere else. GH Action\ scrapes https://ncert.nic.in/textbook.php via Playwright (using the playwright-cli\ skill or playwright-mcp), enumerates every Class \xD7 Subject \xD7 Language combination,\ downloads each chapter PDF, merges them in correct order using pdftk/qpdf, names\ the output {class}-{subject}-{lang}.pdf, releases on GitHub as artefacts. Website\ is the catalog UI that links to GH release URLs. Sorted properly so downloads\ are obvious. Languages: English + Hindi (other regional NCERTs deferred to v1).
NCERT app: dual-mode downloads — GH Release pre-merged + client-side on-the-fly merge — Both download modes: pre-merged PDFs + per-chapter PDFs' Release artefacts (free GH bandwidth + CDN); (2) Client-side on-the-fly merger\ using pdf-lib in browser — user clicks 'Build my book', browser fetches all\ chapter PDFs from ncert.nic.in URLs, merges in browser via pdf-lib WASM, downloads.\ Zero server storage for the on-the-fly path. (3) Individual chapter links also\ exposed for users who want only a few chapters. Three options per book card.
oriz-status-app — self-hosted status page replaces UptimeRobot + Better Stack — Locked 2026-06-22. In-house status page at status.oriz.in CF Worker cron every 5 min probes every URL in FAMILY_* registries, writes to KV, served by sibling read-only Worker behind 60-sec edge cache. Replaces UptimeRobot (commercial-use ban Oct 2024) and supersedes the 10-monitor Better Stack ceiling. Telegram alerts on transition. RSS feed for incidents. 30/90-day uptime rollups.'
Per-app website briefs (2026-06-22 grill lock) — Source of truth for what each of 26 apps does + sections + features. Locked via grill 2026-06-22 (Q-APP-* + Q-NCERT-* + Q-TOOLS-*). Supersedes\ per-app scope files where they conflict. Renames: oriz-lore-app → oriz-lore-app\ (broader scope: book/course/documentary summaries, not just books).
API hosting triple-rail: GH Pages per API + RapidAPI listing + data.oriz.in aggregator hub — Every API repo serves data via THREE rails simultaneously GitHub Pages per API with custom domain `<name>.api.oriz.in` (CNAME). (2) RapidAPI\ marketplace listing (free + paid tiers for monetization). (3) Single `data.oriz.in`\ aggregator app on Cloudflare Pages that catalogs all APIs + provides unified docs\ + dashboard. NO Cloudflare Workers anywhere. Each API repo also ships native distributables\ (APK/MSIX/EXE/PWA) via PWABuilder — even API repos get installable apps.\ 14 APIs scaffolded: existing FII/DII + MMI + 12 new (NSE-BSE tickers, MF-NAV proxy\ of api.mfapi.in, RBI rates, gold/silver, IRCTC PNR, CPCB AQI, global AQI proxy,\ petrol/diesel, pincode, IFSC, India holidays, currency aggregator).
Billing webhook architecture: CF Pages Function → Firestore — Razorpay (INR) + Paddle (ROW) + Play Billing + MS Store \ webhook handlers all land on a single CF Pages Function endpoint per provider\ \ (4 endpoints total). The function (1) verifies the provider's webhook signature,\ \ (2) writes user subscription state to Firestore, (3) returns 200. Zero CF Workers\ \ in the hot path of payments. Each provider's pricing page button is a direct platform\ \ link \u2014 no proxy through our infra. ~1 Pages Function call per purchase."
No Firebase Functions — Blaze requires a card on file, hard blocked — No Firebase Functions, avoids Blaze plan which requires a card on file with no real spend cap. Per the no-card-on-file rule, Functions are excluded. Replaces with: GitHub Actions cron (free for public repos), Cloudflare Workers (100K req/day free), Cloudflare Pages Functions (shared 100K/day free), browser-side compute, static JSON in Pages.
First book: 'My Learnings from the Oriz Project family' — replaces Oriz Me as first draft — First-book pick changed from Oriz Me to Oriz Learnings to 'My Learnings from the Oriz Project family' — a memoir + manual hybrid\ documenting building the oriz family. Quality bar: 'good books, not bad books'.\ Minimum publishing setup: KDP + Play Books Partner Center + Leanpub + Draft2Digital\ (all free signup, all royalty-on-sale, no card). ISBN free from KDP/D2D; not required\ for digital-only on Leanpub/Gumroad.
stats.oriz.in family-wide-stats dashboard + per-app feeds + Changesets + single oriz-app-template — oriz-stats-app at stats.oriz.in shows family-wide usage stats \ aggregate metrics (visits, npm downloads, GitHub stars, books sold, Sentry errors).\ \ RSS published from blog app only (not all 26 apps \u2014 too noisy). Package versioning\ \ via Changesets per-package; auto-bump on merge. Single `chirag127/oriz-app-template`\ \ repo used for every new app via `gh repo create --template`."
Charts: Apache ECharts (lazy per page) covers every chart type — ECharts (Apache-2.0, 50+ chart types) family-wide chart library ~300 KB gzip but lazy-loaded ONLY on pages with charts (zero hit on non-chart pages). Apps that load ECharts: paisa-finance + janaushdhi + stats.oriz.in + blog post embeds + others as new apps need charts. Client-side interactive rendering (no SSR for charts in v0). Provides line / bar / pie / scatter / candlestick / boxplot / treemap / sunburst / heatmap / radar / sankey / parallel / gauge / funnel / geo (map) / 3D / chord / liquidFill / wordCloud / graph (network).
FINAL: Every visual surface per-app; only behavior/utility packages stay shared — Resolves shared-vs-divergent design sequence chrome. FINAL POLICY: every VISUAL surface (Header / Footer / Sidebar / BottomBar / Wordmark / token CSS variable NAMES) is FULLY per-app. NOTHING visual shipped from packages. Only behavioral / utility / non-visual packages stay shared (auth-core, astro-billing, oriz-seo, oriz-analytics, oriz-consent, oriz-ai-providers, oriz-rate-limit, astro-data, astro-pwa, astro-content, astro-forms, astro-distribute, astro-test-utils, omni-publish, oriz-book-build, oriz-ui ContactForm). Legal pages per-app (no shared LegalFooter). Every footer includes 6 standard legal links (/privacy /terms /contact /about /refunds /disclaimer) with per-app visual treatment. Triple-supersedes the on-again/off-again shared-chrome reversals from earlier same-day.
Footer column structure: 5 columns (4 standard + 1 per-app), 4/2/1 responsive, accordion default-closed mobile — Each app footer has 5 responsive columns \ 4 standard (Legal / Family / Connect / Brand) + 1 per-app-specific. Desktop \u2265\ 1024px = 5-column grid. Tablet 768-1023px = 2-column grid (pairs of 2-3 cols stacked).\ \ Mobile <768px = single accordion (default-closed; tap to expand). Family column\ \ shows individual links to other oriz apps + tools + books + packages (mini sitemap)."
Footer per-app design + universal legal section (refines maximalist-footer) — Refines maximalist-footer decision. Each app gets own footer draws its own footer (per-app visual design, per-app content links related to\ that app's surface area) BUT every footer INCLUDES the universal legal section\ (links to /privacy /terms /contact /about /refunds /disclaimer /sitemap /security.txt\ — all in-domain). Pattern: each app's footer is its own component; the legal\ section is a shared sub-component `<LegalFooter />` from astro-chrome that drops\ in. Per-app legal pages content is also CUSTOMIZED per app (the app's own copy,\ not generic boilerplate from astro-chrome/legal/*).
Every app ships all 4 navigation surfaces: Header + Footer + Sidebar + BottomBar — Every app must include all 4 nav surfaces: header, footer, sidebar, nav' Footer at bottom, Sidebar at side, BottomBar mobile-tab-bar at bottom-fixed) so users have maximum navigation options. The 4 surfaces share a family-wide STRUCTURE (CSS/responsive/breakpoints from @chirag127/astro-chrome) but content divergence is per-app: Header is fully divergent (per-app file), Sidebar + BottomBar use the package''s shell with per-app slot content / per-app actions, Footer is the single fully-consolidated surface (mega-sitemap).
Maximalist mega-sitemap footer everywhere + monetization on EVERY app (reversals) — Footer = MAXIMALIST mega-sitemap + monetization every section on every app (reverses per-app-divergent footer from shared-vs-divergent-matrix). Reason: AdSense + Play Store + MS Store + Razorpay approval gates all require visible legal links + family-nav + contact. Mega-sitemap satisfies all gates uniformly. (2) Monetization on EVERY app including janaushdhi (reverses the ''no ads on public-health'' carve-out from ads-allowed-everywhere-except.md). Reason: ''every app should have monetization regardless of category''.
Auth + Billing + Polish + Webhook locks (2026-06-22 evening grill) — Final locks: 6 auth providers, Razorpay TEST, discount codes
Backup everywhere weekly + backup-status dashboard app — Weekly cron backs up to multiple destinations git mirror (already running), Firestore exports to CF R2, Restic snapshots of master to Backblaze B2. New post-MVP app `oriz-backup-status-app` provides a dashboard at backup.oriz.in showing total bytes backed up, per-rail health, last-success timestamps, per-source breakdown. Decoupled from any single host failing.'
Dynamic family-data registry: @chirag127/astro-shell/family-data + auto-discovery cron — Dynamic registry for constantly changing family inventory every app must read from a SINGLE dynamic registry instead of hardcoding the list. Registry lives in `@chirag127/astro-shell/family-data.ts` (TS module). A daily GH Action scans `chirag127/*` repos via the GH API, classifies each by slug suffix (-app / -npm-pkg / -api / -book / -ext / etc.), regenerates family-data.ts, commits + bumps astro-shell version, triggers Renovate auto-PR across all consuming apps. Zero manual edit. Surfaces consuming this registry: footer Family column / sidebar ''other apps'' / home-app index pages / packages-catalog auto-discovery / API hub aggregator at data.oriz.in.
Market-data per repo — GH Actions cron + GH Pages JSON serve, one repo per API — FII/DII + MMI each in own GitHub repo GH Actions scrapes (weekdays post-NSE-close for FII/DII, hourly for MMI) and commits JSON back into the repo's data/ directory. GitHub Pages + raw.githubusercontent.com serve the JSON publicly. Zero Cloudflare Workers, zero shared aggregator repo.
Maximum libraries policy — reverse 'minimal-libraries'; consume community libs heavily — Maximum libraries policy, minimal-libraries reversed MAXIMUM number of community libraries so we write less code ourselves. Every `@chirag127/oriz-*` and `@chirag127/astro-*` package internally uses community libraries as much as possible. Goal: 90% community code / 10% glue. Performance impact mitigated by Astro per-route island hydration + tree-shaking + lazy-load.
SEO + A11y + CDN + SSL + multi-engine indexing (Q3 2026) — Multi-engine SEO + IndexNow auto-submission \ + JSON-LD structured data per page + WCAG 2.2 AA + Pa11y CI gate + Lighthouse\ \ a11y \u226595 required + CF Pages tight cache rules (HTML 1h, assets 1yr, API\ \ 0) + Brotli + HTTP/3 + CF Universal SSL + HSTS preload submission for oriz.in\ \ + robots.txt allow-all (including AI scrapers) + single family-wide GA4 property\ \ with `app` custom dimension."
Shared-vs-divergent matrix family-wide (FINAL 2026-06-22 evening) — Matrix: shared packages vs per-app divergence' Auth FULLY shared. Pricing FULLY shared. Theme tokens API shared, but hex colors\ + type stack PER-APP. Footer DATA shared (FAMILY_APPS/BOOKS/PACKAGES from astro-shell),\ but footer VISUAL per-app per content. Theme: ONE forced theme per app (NO dark/light\ toggle). NOT every app needs all 4 nav surfaces — only what's needed for\ AdSense + Play Store + MS Store approval gates.
Add 4 packages to family — oriz-rate-limit, oriz-analytics, oriz-seo, oriz-consent (22 packages total) — Family expands 18 to 22 packages: rate-limit, analytics, seo, consent
Legal pages package: @chirag127/astro-chrome/legal/* mounted in-domain per app — 8+ legal pages in domain package /sitemap /security.txt) shipped as Astro page components in `@chirag127/astro-chrome/legal/`. Every app mounts them at its own domain (not external legal.oriz.in) so AdSense + Play Store + MS Store + Razorpay approval gates are satisfied. Single source of legal text; same content everywhere; design adapts to each app's theme.
@chirag127/oriz-ai-providers (18th package) + chirag127/oriz-ai-providers-data data repo — @chirag127/oriz-ai-providers aggregates free AI providers LLM API (Cerebras, Groq, Cohere, NVIDIA NIM, GitHub Models, Cloudflare Workers\ AI, HuggingFace, Mistral, SambaNova, OpenRouter, LLM7, OVHcloud, Pollinations,\ Kilo Code, Ollama Cloud, Z.AI, Aion Labs, SiliconFlow, ModelScope — 20+ providers).\ Provider data + model lists + rate limits + base URLs maintained in a SEPARATE\ data repo `chirag127/oriz-ai-providers-data` so the package can stay slim and\ the data can be updated independently of the code. Priority order: no-key-required\ providers first (anonymous OVHcloud / LLM7 / Pollinations), then free-with-key\ providers as fallback chain. NIM + OpenRouter demoted from primary.
Single family-wide pricing page (ad-free is the only paid feature) — Shared pricing page across all oriz apps \ so it's identical everywhere. The ONLY paid feature family-wide is 'ad-free' \u2014\ \ remove AdSense + AdMob. Same price tier across web + Play + MS Store. Single Razorpay/Paddle/Play-Billing\ \ link. No per-app paywall complexity."
Observability, AI, search, auth, DB stack (Q3 2026 lock) — Service picks locked 2026-06-22. AI: @chirag127/oriz-ai-providers' (20-provider fallback chain — OVHcloud / LLM7 / Pollinations anonymous first,\ then Cerebras / Groq / NIM / OpenRouter / etc keyed) — see decisions/architecture/oriz-ai-providers-package.\ Search: Pagefind for static + Algolia free hybrid. Errors: Sentry free + OSS tier\ apply. Uptime: UptimeRobot free 50 monitors. Auth: Firebase Auth (Spark). DB:\ Firestore only. I18n: English-only v0 + Crowdin OSS community translations. Privacy:\ single family-wide /privacy page. Cookie consent: Klaro EU + DPDP India geo-route.
Tool app feature scopes (locked 2026-06-22 — full client-side feature sets per app) — Final feature scope per tool app. All 100% client-side server, no upload). Heavy features deferred to v1+ where bundle size would blow budget. Per-app feature list grilled and locked 2026-06-22.
Per-surface monetisation recommendations — what rail to use where — Payment rail per distribution surface (Play, MS Store, web, etc.)
Monetisation playbook — only rails that do NOT require a card on file — Master matrix of no-card-compatible monetisation rails
Three-tier pricing: Free / Pro / Max — single package, minimum manual work, community-support only — 3 tiers Free/Pro/Max. Single @chirag127/astro-billing package
data.oriz.in aggregator app + centralized auth.oriz.in + Phone-Auth Pro-tier-only — oriz-data-aggregator-app + central auth hub \ at `data.oriz.in` renders ECharts dashboards + JSON browser for all 14+ API repos\ \ (separate from per-API GH Pages). (2) `auth.oriz.in` is the central Firebase Auth\ \ domain; all apps redirect there for sign-in; redirect back after success. (3)\ \ Firebase Phone Auth is enabled but UI-gated to Pro tier (Phone SMS costs $0.05/SMS\ \ ~ \u20B94/SMS \u2014 not free; rate-limit free users to 0/day, Pro to 5/day, Max\ \ unlimited). (4) Authentication ONLY in apps, never APIs (APIs serve pure JSON,\ \ no auth)."
Domain registrar exception: Spaceship card-on-file auto-renew (oriz.in) — Spaceship exception to no-card rule: oriz.in auto-renew only
Single env source: c:/D/oriz/.env ? auto-push to chirag127 GH Org Secrets ? apps consume at build — Master .env single source. GH Action pushes org secrets daily
Three-env file split — .env / .env.development / .env.production — Three env files per NODE_ENV. Sops-encrypted. Loaded via Vite/Astro
Payment architecture — direct platform links via CF Worker click-tracker — Direct platform links, redirect to payment provider to a provider's hosted checkout (Razorpay Payment Page, Gumroad URL, Paddle checkout\ link, Substack subscribe URL). Provider hosts the checkout; we host the button.\ User picked a small CF Worker proxy that logs the click anonymously to CF Analytics\ Engine and then 302s to the platform URL — ~1 Worker call per checkout, 20x\ headroom on the 100K/day free envelope. Zero payment secrets on our infra (no\ API keys); all payouts go to the creator's bank account after the platform's own\ KYC. Per-region routing: Razorpay (INR) + Paddle (USD/EUR/GBP/ROW) + Gumroad (digital\ downloads) + Substack (newsletters) + Play Billing (in-app).
Razorpay donation button — pl_T4iEPIDcALKLPk, one-click flow — Razorpay-hosted donation button mounted on site on every app''s /sponsors route + oriz-cs-me-app footer. One-click: opens Razorpay-hosted donation page; user picks amount; payment received. Separate from subscription flow (donations are one-time, not recurring). Integrated as shared <SponsorButton /> in @chirag127/astro-billing.
Headroom: always-on proxy (not on-demand) — Headroom persistent background proxy. Idle RAM for zero cold-start. Starts at login
Headroom install: all paths (Claude Code + ScriptCat + standalone) — Headroom 3 paths: CC (CLI), ScriptCat, standalone. One binary, three entry points
Headroom proxy auto-start via Windows Task Scheduler at login — Headroom launches at logon via Task Scheduler. Runs as logged-in user with env + creds
Knowledge hierarchy: add log/, core-concepts/, runbooks/ as top-level dirs — OKF adds log/, core-concepts/, runbooks/ top-level dirs
Memory -> knowledge migration plan — MEMORY.md durable entries migrated to OKF, memory retains ephemeral
oriz-me added to the family as the 11th site — 2026-06-19: oriz-me added as submodule under sites/
100-year strategy locked — 16-point strategic contract: 50-yr horizon, 10-min/day, JSONL
Age-gating policy adopted for adult-content sections — Adult-content items behind 18+ gate
me.oriz.in does NOT publish journal; journal stays auth-gated — Journal: numeric aggregates public, text auth-gated
Lifestream JSONL in git is canonical; Turso is warm cache — chirag127/oriz-me-data holds canonical JSONL events sharded by year by year. Turso libSQL is a rebuilt warm cache for live edge reads, not a source of truth.
One-branch-only rule: main branch only — All repos: main branch only. No feature/fix/chore branches
All 11 sites have v2 designs landed — v2 designs committed + pushed for all 11 sites. Cross-links fixed
Agent configs — dedicated submodule, minimal user-overrides, umbrella orchestrates sync — chirag127/agent-configs is a public submodule at repos/own/infra/agent-configs holding only user-diverges-from-defaults keys. Umbrella scripts/sync-agent-configs.ps1 + Oriz-SyncAgentConfigs scheduled task writes to global paths at logon.
Enable auto-sync scripts for cross-machine parity — Reverse the 2026-06-29 manual-only stance; MEMORY sync + globals-derived + mirror hosts now auto on hooks/cron with grill-on-drift.
Boone as OKF search engine — replaces stdlib prompt-lookup — Community boone CLI (BM25 + graph) adopted for OKF search; swap into UserPromptSubmit hook; stdlib script kept as fallback.
Publish knowledge/ to knowledge.oriz.in via Kiso + CF Pages — OKF bundle mirrored to public URL; Kiso as build engine; CF Pages host; llms.txt + sitemap.xml + RSS/Atom on top.
Triple-fanout skills publishing — skills.oriz.in + registry + GH Pages — agent-skills submodule published to CF Pages branded site + skillshare/openskills registry + GH Pages default. Maximum reach.
Deferred infra plan — folder reshape + submodule audit + repo template + Greasyfork prefill — 4 infra work items scoped and locked but deferred to a follow-up session. Documented here so the plan survives context churn.
Dropped-agent configs deleted early — override 90-day cooldown — .opencode/.kilocode/.antigravity/.mimo/ config directories deleted now instead of waiting 2026-10-02; pointer stubs preserved for AGENTS.md portability.
Env pattern — .env is single source, MCPs read system env vars — .env.enc (sops+age) → .env → user env vars daily. .mcp.json uses ${env:VAR} refs. No secrets in configs, no per-agent auth files.
Fleet reversal — CC + OpenCode + Kilo (2026-07-03) — Reverse 2026-07-02 cut-to-CC-only. Reintroduce OpenCode + Kilo Code. All 3 agents share skills via npx skills auto-sync from chirag127/agent-skills.
Public knowledge MCP server — chirag127-knowledge-mcp — MCP server exposing knowledge/ OKF bundle over MCP; boone-backed; no auth; any AGENTS.md-reader can wire and query.
MEMORY.md cross-machine sync via chirag127/claude-memory + sops+age — Private GH repo with sops+age encrypted MEMORY.md and per-project memory/ trees. Auto-push on session end, auto-pull on session start.
OKF build engine — Astro custom (Kiso deferred) — Fresh verification found Kiso is HN-post-only (no npm/repo). Fallback to custom Astro via api-fleet-template pattern. Revisit Kiso when installable.
OKF publishing conventions for oriz bundles — Filenames, feeds, structure for public OKF bundles at knowledge.oriz.in / skills.oriz.in; adopts Kiso defaults + adds RSS/Atom first-mover.
OKF v0.2 additions upstreamed to Google — PR to GoogleCloudPlatform/knowledge-catalog proposing optional `confidence` and `durability` fields; agentmemory precedent cited.
Everything on chirag127; oriz-labs empty (namespace-squat) for 6 months — 12 repos back on chirag127 with short names. oriz-labs held empty for defensive namespace-squat. 6-month org-shape freeze from 2026-07-03.
Repo code-size ceiling grounded in 2026 web practice — Grill-driven pick of 200K warn / 2M fail per own repo, sourced from 12 practitioner citations. Dagger TS enforces via GHA.
Auto-generate skills from knowledge/rules — Every knowledge/rules/agent/*.md compiled to a SKILL.md so rules are invokable as skills; cross-linked, not merged.
Screenpipe upstream contribution burst 2026-07-03 — Two grill-driven session waves filed 19 PRs + 18 issues on screenpipe/screenpipe covering UX, perf, security, MCP spec, architecture, docs, CI.
Strix AI pentesting — adopted for oriz API fleet — Strix open-source agentic DAST+LLM pentesting wired into ci-astro-api shared workflow.
Tampermonkey userscript audit — 2026-07-03 — Automated inventory + static-scan of 137 installed userscripts. 1 provable finding filed; rest logged for future triage.
Chromium Engine Hardware Scaling Profiles — Chromium optimization profiles: cloud vCPU, hybrid local, mobile

architecture (32)

Automation Minimalist & Modern Stack — Best minimalist stack for automation and testing
CLI Tools Minimalist & Modern Stack — Best minimalist stack for CLI tools
C++ Minimalist & Modern Stack — Best minimalist stack for C++
C# Minimalist & Modern Stack — Best minimalist stack for C#
Databases Minimalist & Modern Stack — Best minimalist DB stack: serverless SQL, edge SQL, KV, object storage
Extensions Minimalist & Modern Stack — Minimalist stack for browser/editor extensions
Go Minimalist & Modern Stack — Minimalist stack for Go and dev tools for Go.
Hosting Minimalist & Modern Stack — Minimalist hosting: static frontends, edge workers, containers
Java Minimalist & Modern Stack — Minimalist stack for Java
JavaScript/TypeScript Minimalist & Modern Stack — Minimalist stack for JavaScript/TypeScript and dev tools for JS/TS.
Python Minimalist & Modern Stack — Minimalist stack for Python and dev tools for Python.
Rust Minimalist & Modern Stack — Minimalist stack for Rust
API routes — apps/api/src/routes/ structure — Hono Worker splits routes by concern under apps/api/src/routes/ \ \u2014 contact, recaptcha, razorpay, firestore, turso, auth. Each folder owns\ \ the integration with one external service."
API umbrella — one Hono Worker at api.oriz.in — Single Hono Worker at api.oriz.in serves all family API routes See the decision file for why.
Hono RPC type-sharing — `hc` client across sites — API consumers get full type inference from Hono Worker via rpc client. See the decision file for why.
Layer 5 — compute, in three tiers — Compute split: GH Actions cron, CF Workers, specialized' Workers (edge runtime), and the user's browser. Each tier has a free quota and a clear remit.
Service Bindings — future privileged-Worker split — CF Service Bindings: zero-cost, zero-hop RPC between Workers' Workers. Reserved for a future split where the Hono umbrella Worker delegates privileged auth/billing logic to a separate "auth-core" Worker.
Canonical store — JSONL in chirag127/oriz-me-data — chirag127/oriz-me-data git repo authoritative store for lifestream events. JSONL append-only files are the source of truth; everything else is derived.
Cloud DBs are caches, not sources — Firestore, Turso, R2 are caches rebuilt from canonical JSONL git store on every deploy. If any of them dies, the next deploy reconstructs it from JSONL.
Events table schema (Turso warm cache) — SQL shape lifestream JSONL normalised into for Turso \ warm cache. Lives concretely in oriz-me but the contract is family-wide \u2014\ \ any site reading lifestream events sees this shape."
Layer 4 — database, sharded by data shape — Data shapes spread across free tiers by type load so no single quota gets exhausted. Git for canonical, Firestore for user state, Turso for warm cache, browser for per-user search, R2 only when needed.
Layer 1 — static hosting on Cloudflare Pages — Cloudflare Pages free primary host for all sites and extensions catalog. Unlimited bandwidth, no card required, fails-closed at quota.
Layer 2 — survival fallback on GitHub Pages — Every site static fallback to chirag127.github.io/site \ every push to main. If Cloudflare Pages dies, /work + /me + /legal still serve\ \ from github.io. Per the 100-year strategy \xA716."
Extension distribution — Chrome, Firefox, Edge, automated — Each extension own GH repo, submoduled under extensions/ Each repo has its own CI workflow that publishes to Chrome Web Store, Firefox Add-ons, and Edge Add-ons on release. Landing pages live on extensions.oriz.in (with a copy at oriz.in/extensions).
Master pointer as production SHA — Master repo submodule pointers = production SHA state of the family. Bumping a submodule pointer + pushing master = deploying that submodule to production via the matrix workflow.
Submodule pattern — each site/package/extension is a separate GitHub repo — Each site/package/extension standalone GH repo repo added as a git submodule under sites/, packages/, or extensions/. The submodule has its own commits, releases, CI, and main branch. The master oriz repo stores a SHA pointer per submodule.
Subscription flow — Razorpay → webhook → Firestore → every site — One subscription unlocks everything via Razorpay webhook lands at api.oriz.in, Worker writes users/{uid}/subscription, every site and extension reads that doc to gate features.
Cross-site auth via auth.oriz.in — auth.oriz.in shared across all *.oriz.in apps subdomain and every Chrome/Firefox/Edge extension. One sign-in, one Firebase user, every surface.
Layer 3 — auth on Firebase Spark forever — Single Firebase project on Spark plan, never Blaze auth domain auth.oriz.in shared by every site and every extension.
Package isolation rule — every external service wraps in a typed package — External services wrapped in typed @chirag127 packages so swapping providers is a package version bump, not a 50-file rewrite. Any new service crossing 3+ sites' boundary gets a wrapper on first introduction.
The twenty-three packages — the locked oriz family package set — 23 npm packages: 10 Astro, 4 auth, 5 cross-cutting, 4 specialized
[REDIRECT] the-six-packages.md → the-23-packages.md — Legacy file, canonical set in the-23-packages.md (18 packages locked 2026-06-22).

rule (178)

Agent minimum-context protocol — find before deriving — How AI agent operates on this repo with minimum upfront token cost Read knowledge/_navigation.md FIRST. Grep before writing. Terse self-contained files. [[wikilinks]] for chaining. Commit knowledge same-turn. Plus a cookbook of recurring tasks with entry-point file paths.
Self-update on every decision (durable info only) — Decisions written to knowledge/ same session
Fork discipline — minimum diff, rebase-friendly, upstream-aligned — Minimum-diff forks, rebase-friendly, upstream-aligned
Git identity — always use chirag127's GitHub noreply email — chirag127 noreply email for all commits
Profile README must cross-link chirag127 ↔ chirag127 — chirag127 ↔ chirag127 cross-link in profile READMEs
Recruiter strategy: optimize pinned repos + contribution graph, not the repo list — Optimize pinned repos + contribution graph for recruiters
Fork model: chirag127-owned + upstream tracking + weekly auto-sync — Forks live under chirag127 personal account. origin=chirag127 + upstream=source. PRs directly from origin. Weekly auto-PR sync from upstream.
Forks are submodules, never plain clones — Every fork under repos/frk/ is added via `git submodule add`, never via `git clone`. Locks fork pointer in umbrella, keeps umbrella tree clean.
All durable knowledge in knowledge/ — caveman style, no exceptions — Everything worth remembering lives in knowledge/ as an OKF file. Caveman style: terse, dense, no filler. README/AGENTS.md stay lean.
No fork divergence — upstream PRs only — Local forks in repos/frk/* stay byte-identical to upstream main. Every local change files as an upstream PR immediately.
Terse upstream issues + comments — less is less hallucination — GitHub issues and comments: short, factual, no filler. Every unverified claim is a potential hallucination. Min words = min risk.
Thank maintainers on every upstream issue/PR/comment — Every upstream contribution ends with a one-line thanks to the maintainer for their work on the project.
Windows shortcuts/wt-spawned shells: use absolute paths to .cmd/.exe binaries — Windows Terminal tabs launched via wt new-tab + a -Command string don't reliably inherit the User PATH. Always use the absolute path to npm.cmd / pnpm.cmd / python.exe etc. when constructing startup scripts.
2025 agents.md discipline — tight context, knowledge bundle, don't drift to 2026 yolo — User locked 2025 mindset 2026-06-23: AGENTS.md stays short sharp, knowledge/ is the brain, every concept gets a file. Reject the 'just let\ agents figure it out from context' 2026 yolo for non-toy projects. For oriz family\ this means: AGENTS.md ≤200 lines pointing at README.md and knowledge/, never\ inline rules in AGENTS.md if a knowledge file exists, prune stale knowledge weekly,\ treat context as a precious limited resource.
Auto-grill on architectural decisions — Before multi-file architectural choice — grill first \ framework, data model), agents MUST run the grill skill or its inline equivalent\ \ (3\u20134 ranked-recommendation questions via multi-choice question prompt). Decision must\ \ be locked into knowledge/decisions/ before code lands. Locked 2026-06-23 in response\ \ to user explicitly choosing the auto-grill cadence. Compounds with self-update-on-every-decision:\ \ grill produces the decision, that rule files it."
Storage decision needs explicit grill — User voices DB/storage concern → grill on concern, not preemptively pick different stack
Community packages first — prefer external dependencies over hand-rolling — Prefer well-maintained community packages over hand-rolling
AWS Lambda EXCEPTION to no-card-on-file rule — AWS Lambda exception to no-card rule
Cloudflare Pages = apps only. Everything else = GitHub Pages — CF Pages for apps, GH Pages for everything else
Card-on-file allowed BUT only on free-tier-safe providers with hard cost controls — Card-on-file OK with hard $0 spend cap
Knowledge — hard-delete superseded files — Superseded decision: git rm old file same commit as new. Audit trail in git history
Atomic packages — extract lazily on second use — 2+ apps need same logic ? extract to @oriz/* or oriz-* package. Concern-atomic (3-5 exports, 100-300 LOC). Build only when forced
Fork features ? also file upstream issues — Feature patched in repos/frk/ ? file upstream issue requesting same. If merged, drop patch
GH org secrets, build-time inject — Shared tokens flow from GH org-level Actions secrets into each repo CI, baked into Astro static output
GitHub repo names are brand identity — Prefer renaming local folder over renaming GitHub repo. GitHub repo names = brand identity
Lean by need, not count — Build-gate applies to npm deps as features. No min/max dep count. Each dep justifies itself
Scope-cut: only shipping survives — Only shipping-content repos survive. In-progress/scaffold/will-build-someday archived. 33 repos cut
vsce: publish VS Code extensions to all marketplaces — VS Code extensions ALWAYS publish to both VS Code Marketplace (vsce) + Open VSX (ovsx). Both tokens in .env
Don't rebuild software that already exists completely free — Don't rebuild software that exists free
Every repo README must carry a star-this-repo badge near the top — Star-this-repo badge near top of every README
Userscript @author metadata uses GitHub handle `chirag127` — Userscript @author = chirag127
React > Preact — ecosystem over bundle size — React over Preact — ecosystem over bundle size
AGENTS.md is a living doc — update when patterns recur — AGENTS.md is not written-once. When a recurring issue surfaces during development (tool quirk, banned pattern, style rule), update AGENTS.md before moving on. Solve once, document, forget.
Context interview — agent asks user first when uncertain — When unsure what context is needed for a task, agent asks the user targeted questions BEFORE attempting. 'Ask me any further questions you need to achieve the best result.'
Distill the winning prompt — save the retrospective one-shot — After long back-and-forth to reach a working answer, ask Claude to write the prompt that would have gotten there first-try. Save that prompt. Skip the iteration next time.
Draft ≠ send: external comms need explicit approval — Never send/publish/post/comment/PR-file externally without explicit human approval. Draft means draft. Insurance-agent-sent-email pattern is the failure mode this prevents.
Fable 5 prompting — 6 habits + safety-route awareness — Six locked prompting habits for Claude Fable 5: give why, negative-prompt, act when enough, make it prove, don't ask for reasoning, say less. Plus safety-router awareness (Fable→Opus 4.8 on suspicious intent).
Grill before adding any rule — choose the right artefact type — Every proposed rule triggers a grill to determine if it belongs as a rule, skill, hook, knowledge file, or AGENTS.md line. Adding rules without grilling = knowledge bloat.
Ground first, ask second — For tasks requiring domain knowledge or fresh context, send a research/ground prompt FIRST, then the action prompt. Two-prompt pattern. Reduces hallucination + generic answers.
ICC prompt formula — Instructions + Context + Constraints — Every non-trivial prompt must have all three: what to do (instructions), what to know (context), what shape/limits apply (constraints). Order doesn't matter, completeness does. Optional: output example.
Iterate before creating a skill — Never invoke skill-creator on the first attempt. Iterate manually 3-5 times, tag responses as good/bad with reasoning, THEN distill into a skill. Prevents overfit-on-one-example.
Review per-project memory monthly, prune stale entries — Auto-saved memory files (~/.claude/projects/*/memory/MEMORY.md) get stale — 'currently working on X' after X shipped. Monthly review + prune.
Own the memory, rent the intelligence — Memory + skills + orchestration are portable and belong to you. Intelligence (frontier models) is rented — swap providers freely. Never couple your knowledge to one vendor's tool.
Practical vibe coding — the middle way — Neither over-plan nor yolo. Iterate feature-by-feature with an anchoring AGENTS.md, focused ICC prompts, behavior-constraints, and verify each before starting next. The umbrella framework.
Proactive creative workarounds — don't just report blockers — When a constraint blocks the ideal path, suggest a creative workaround before reporting the blocker. Blocked = opportunity to be creative.
Proactively add rules and knowledge — don't wait to be asked — Every session that surfaces a durable insight, decision, taste rule, or pattern must write it to knowledge/ or memory/ in the same turn. Don't wait for user to ask.
Session hygiene — break sessions between distinct features — Reset chat/session when moving between distinct features. Stale context leaks confuse the agent and waste tokens. Stay in same chat only when tied to what you just built.
Small composable skills, not mega-skills — One skill does one thing well. Chain 4-6 small skills > one 500-line mega-skill. Enables auto-invocation per sub-task + composition across workflows.
Subagent transparency — show what they do, don't silent-pass-through — When spawning a subagent, show what it will do + return format + verification plan. Summarize subagent output back to user before acting on it.
Ticketing primitive — agent operations visible via TaskCreate — Every multi-step operation and every external-state operation goes through the task system. No hidden work in chain-of-thought.
Everything should be in Dagger — GHA/GitLab/Codeberg are thin adapters only — All CI/CD logic lives in Dagger TS modules. GitHub Actions, GitLab CI, Woodpecker, Codeberg are 5-line wrappers that call `dagger call`. No real logic in YAML.
Claude Code skill triggers — phrase → skill reflex map — When the user types these phrases, fire the matching skill automatically without confirmation.
Never use native web tools — only MCP-based web tools — WebFetch and WebSearch (native Claude Code tools) are blocked from this point. Use MCP web tools only. See knowledge/services/broken-mcp-servers-2026-06-28.md for which are working vs broken.
Delegate to sub-agents by default — researcher for reads, Haiku for batch — ACTIVE every response. Use sub-agent before reading 3+ files. Isolated context; only summary returns. Cuts tokens 40-70%
Minimum everything — fewest lines, fewest tool calls, fewest packages — Hard rule. Smallest unit of everything. Per response, per file, per workflow
Output minimalism — no preamble, no restatement, answer-first, no abstract language — ACTIVE every response. Bans 4 verbosity anti-patterns. Cuts ~20-40% beyond Caveman
Ponytail — lazy senior dev (ULTRA level) — ACTIVE every code-gen response. 7-rung ladder picks laziest working solution. ULTRA = no-code, one-line, zero abstraction
Don't recreate what already exists freely as open source — Before forking/scaffolding/building: 2 web searches confirming no free OSS equivalent. If exists, use it
Edit-mode preferences — tool choice + task tracking — Edit > Write, batch parallel tool calls, task-list for 3+ steps, no .md deliverables
Never recreate headroom-proxy container without checking entrypoint — headroom-extras ENTRYPOINT already headroom. docker run CMD must start with proxy..., not headroom proxy...
User prefers features-on when cost is small — User prefers features-on when cost is small
Grill-to-knowledge — every grill-me answer lands in knowledge/ — Invoke grill-me or design Q&A — write results to knowledge/ EVERY locked answer (question stem + chosen option + rejected options + 'why') MUST land in knowledge/ in the same conversation. No locked answer may live only in chat history. The conversation context is the audit trail; the decision file is the durable truth.
Keep knowledge fresh — read first, write current truth, delete obsoletes — Every session reads knowledge before acting, writes decisions into knowledge/ as CURRENT TRUTH (not historical logs), and deletes obsoleted content same-turn. Knowledge files are snapshots of what IS, not journeys of how we got here.
Don't create .bak folders — User rejected src.bak/ pattern. Git history = durable backup. Destructive edit? ASK FIRST
"Free for the developer" means services we consume, not license — \"Free for developer\" = services we consume free (no card, no quotas). NOT code OSS
PWABuilder is primary PWA→native converter — PWABuilder (Microsoft, free, CLI) = primary PWA→native converter. Tauri demoted to opt-in. iOS PWA-only
Repo slug `-npm-pkg` suffix for npm packages — GitHub repo slugs for npm packages get -npm-pkg suffix even though npm name does not. 22 packages converged
Design divergence is NOT duplication — Per-app design divergence, not duplication
Astro version pin: major in package.json, auto-update minors weekly — Astro pinned at major, minors auto-update weekly
Tests in parallel + master `pnpm install -r` is THE install command — Tests parallel, pnpm install -r from master
Cloudflare Pages only — every website and every app hosts on CF Pages — CF Pages family hosting lock
No subscriptions — no service requiring a recurring paid plan — No recurring paid subscriptions
Communication is STT-friendly — accept transcription noise, infer intent — STT-friendly communication, infer intent, ≤4 MCQ options
iOS is PWA-only — user has no Mac — iOS PWA-only, no Apple devices
Linux/Ubuntu only on CI runners — never Windows or macOS — Linux/Ubuntu only on CI runners
No card on file — one-time prepaid OK — One-time prepaid OK, no recurring cards
Automate everything — never deliver a runbook — Ship one executable script per setup/host/deploy request. Manual steps = defect
Bitwarden CLI as cross-machine secrets source-of-truth — Bitwarden CLI (bw): canonical age key retrieval + secondary secrets backup. Read-only locally; updates via Web UI
Caveman — terse prose discipline — ACTIVE every prose response. Drop articles, filler, pleasantries, hedging. Code unchanged. Drop terse mode for irreversible actions
Don't install MCP tools already bundled in Smithery toolbox — chirag127 Smithery = meta-toolbox. Check before adding separate MCP server
Firebase: use the CLI directly, never install Firebase skills — Firebase CLI + agent context enough. No skill wrappers. Saves context, kills doc rot
Grill me properly before non-trivial work — Default grill-mode for >1 interpretation. Walk decision tree branch-by-branch. Surface assumptions, lock, act
kepano/obsidian-skills: global install — Steph Ango obsidian-skills cloned to ~/skill-sources/; 5 sub-skills symlinked global
MCP env credentials — Win env vars + Smithery profile (both layers) — MCP env vars sync via Win system env (local) + Smithery profile (cross-machine). Never commit values
MCP servers: use workspace scope, not global — Workspace-scoped MCP in committed .mcp.json. claude mcp add -s project. Default scope wrong
No dual-remote backup. GitHub IS the backup. — Never add second remote to forks. chirag127 fork on GitHub = backup. Stop re-asking
PowerShell scripts: ASCII only (no em-dash, smart quotes, etc.) — PS 5.1 without UTF-8 BOM reads as Windows-1252. Em-dashes + smart quotes break parser. Use ASCII hyphens + straight quotes in .ps1
PowerShell: native commands writing to stderr trip strict mode — Cargo/winget/npm/gcc print to stderr. PS 5.1 + EAP=Stop wraps stderr in RemoteException. Pipe through cmd /c ... 2>&1
Always search the web at least twice before any non-trivial decision — Two independent web searches before recommending tool/hosting/library/API/architecture. No memory-only answers
Direct commit to main on own repos; branches only for upstream contributions — No feature branches on chirag127/* or chirag127/*. Commit to main. Branches only for upstream PRs
Web search — 3-MCP fallback chain (10 engines, no keys) — searxng + duckduckgo + open-websearch. 10 engines, no API key. Try in order on failure
chirag127/backup is the new-laptop bootstrap + disaster recovery repo — Private repo. Bootstrap: one-command new-laptop setup + restic recovery + encrypted secrets (sops+age)
Try multiple alternatives on failure — never stop at first fail — Website/API/tool/install failure: try 3+ alternatives before reporting blocker
5-agent workspace setup: the AI agent, OpenCode, Cline, Kilo Code, Antigravity — Workspace supports exactly 5 agents. All config inside C:\D\oriz\. Never touch global files
Obsidian vault: minimal plugin set — Only 3 Obsidian plugins: Terminal, Templater, Dataview
Always Read a file before Edit — Always Read file before Edit in current session \ enforces this; the rule restates the why so agents don't fight it \u2014 it prevents\ \ stale-match failures and accidental clobbering."
No ad-slot rectangles reserved in markup — No reserved ad-slot divs in markup
No emoji in site chrome — No emoji in site chrome — SVG icons only
Always install the latest version of every dependency — Always install latest version of every dependency
Conventional commits — Conventional Commits prefixes for every commit
Never force-push to main — Force-push to main needs explicit user instruction
Never call Web3Forms from server-side code — Web3Forms browser-only, never server-side
One branch only — main — Only main branch across all repos
Push to main by default — no explicit say-so needed — Push to main by default without explicit say-so
Apply the role suffix to every new repo, and audit before publish — Role suffix on every repo slug
Every repo in the family must work independently when cloned alone — Every repo works independently when cloned alone
pnpm is the package manager for every JS repo in the family — pnpm mandatory across oriz family
No firebase-admin inside Cloudflare Workers — No firebase-admin in CF Workers, use REST
Auto-only tracking — Auto-only tracking for system metrics
Future decisions override past decisions — Chat contradicts file → chat wins, update same turn
Match the surrounding code style — Match surrounding code style when editing
Never delete an empty placeholder repo without explicit user authorisation — Never delete empty placeholder repos without user OK
Never hit a free-tier quota — Architect for headroom, never hit quotas
Parallel fan-out by default (background subagents) — Parallel fan-out via background subagents
User prefers atomic split over consolidation — User prefers atomic split over consolidation
User prefers deletion over archive for superseded repos (same-day migration) — User prefers deletion over archive for superseded repos
User prefers per-product brand over family chrome — User prefers per-tool brand over family chrome
User prefers same name across GitHub repo and npm package — Same slug across GitHub repo and npm package
User prefers strict-no-toggle interpretation of locked rules — User prefers strict-no-toggle for locked rules
User prefers wider topical coverage over narrow SEO concentration — User prefers wider topical coverage over narrow SEO
No hardcoded secrets — everything via envpact — No hardcoded secrets, envpact provides at runtime
Agent fleet parity: same rules + MCPs across all agents — All fleet agents share same rules + MCP servers. Sync via scripts/sync-mcp-configs.mjs. No private rule sets
Rule additions land in 3 places: concept file + AGENTS.md table + count — Add rule: write to knowledge/rules/ + AGENTS.md entry + bump section count. All three same commit
Claude Code latency: keep cache hot, route through Hr, balance speed/accuracy/cost — Per Anthropic's prompt-caching docs, April 2026 incident postmortem, and 2026-06-29 grill-me settings rebalance. Pick model + effort at session start, don't change mid-task. Route through Headroom. Use skill triggers (slash commands) over prose discussion.
Globals derived from workspace by script (with grill on drift) — .mcp.json + workspace anchors canonical. Globals synced by scripts/sync-globals.mjs. Fires grill-me on drift
Junctions on Windows, symlinks on Unix — Use directory junctions on Windows (mklink /J), symlinks on Unix (ln -s). No Developer Mode needed
Karpathy — surface uncertainty, clean orphans, goal-loop execution — ACTIVE every coding task. State assumptions. Surface ambiguity via MCQ. Clean orphaned imports. Define success criteria + loop
MCP config single source of truth — .mcp.json canonical MCP config. All 5 agents sync via scripts/sync-mcp-configs.mjs. Never edit per-agent configs
Run okf-prompt-lookup before answering knowledge-touching prompts — Every agent must surface top-3 OKF concept files before answering any non-trivial prompt. Claude Code does it via UserPromptSubmit hook; other agents must run scripts/okf-prompt-lookup.ts themselves.
Claude Code settings balance — speed × accuracy × cost (2026-06-29 pin) — 12 settings.json picks from 2026-06-29 grill. Opus-default + always-thinking-floor + adaptive-on + 85% compact + agent-teams-on
Read the file, not just the grep, before claiming a gap — Claims about external project gap must be backed by Read of source file — not grep alone
MCP forks live in repos/frk/-mcp/; fixes go upstream via PR — Fork MCP servers to frk/ and PR upstream
MCP server repo naming: -mcp suffix — MCP repos use <name>-mcp suffix
Workspace Root Cleanliness — Workspace root is canonical-config-only. No generated, derived, or junction content lives here — only committed-first source files.
Grill the user on every new input that contradicts existing knowledge — When user contradicts/narrows/widens/reverses knowledge — confirm before acting a decision already in knowledge/, the agent must explicitly call out the delta, ask the user to confirm whether to overwrite knowledge or treat as one-off, and only then act. Latest user input is the source of truth ONLY after explicit confirmation.
Grill on LOC removal >= 50 lines per sweep (TIGHTENED 2026-06-22 evening) — TIGHTENED 2026-06-22: threshold dropped from 1000 LOC 50 LOC. When a dedup/refactor/cleanup sweep removes ≥50 lines of code in\ a single agent action, the agent MUST surface this as a delta, ask the user MCQs\ about what was removed + why, offer restoration paths, and confirm before deleting.\ Reason: 50-LOC sweeps can hide substantive functional removal (an entire component,\ a route, a feature). Design pattern consolidation safe ONLY after grill; content/feature\ deletion NEVER safe without grill.
Frontend-design skill: distinctive intentional visual design for every UI — Distinctive intentional visual design for every UI
Per-app distinctive frontend design — adopt the frontend-design skill principles family-wide — Each app gets distinctive visual identity, same chrome stays family-wide
No Firebase Cloud Functions — Blaze requires a card on file — No Firebase Functions — Blaze requires card
No PAID self-hosting — free + no-card-on-file providers are fine — Self-hosting OK on free / no-card providers
One-level subdomains only — never two levels deep below oriz.in — One-level subdomains only below oriz.in
Shared-tenant-by-default for every 3rd-party service — Single shared tenant for every 3rd-party service
Every AI provider adapter must be OpenAI-compatible (SDK schema) — Every AI adapter uses OpenAI SDK schema
Always parse 'Other' answers in MCQs for additional context beyond the literal question — Parse MCQ 'Other' answers for extra directives
Telegram channels and roles (restored 2026-06-22) — 4 Telegram channels in Oriz namespace
Adaptive commit granularity — Commits sized to work unit: single decision = 1 commit; batch grill = 1; refactor = 1 per unit
Headroom scoped-use policy — Headroom (Hr): input-compression proxy only. No memory/Qdrant/TOIN/learn. Docker-only
Knowledge-only, no memory dual-write — Durable prefs + locked decisions ? knowledge/ ONLY. Not mirrored to MEMORY.md
Loop engineering for AI agents — AI agent loops across engines/tools with fan-out, fallback, self-correction. No infinite loops
MCP no-key in repo, keyed in Smithery — No-API-key MCP servers committed as configurable entries. Keyed/auth MCP servers go in Smithery toolbox
Memory file mapping by `type` field — Migrating MEMORY.md to knowledge/: type field determines directory (rule?rules/, decision?decisions/, etc.)
OKF graph discipline (inspired by okf-mcp) — Validate cross-links, prefer index-scan over directory-scan, propose-first authoring, structured graph queries
Per-batch grill log granularity — Grill sessions logged at batch granularity — one log per session. Lives in knowledge/log/grills/
4 options per MCQ (default) — MCQs: exactly 4 ranked options (Recommended + 2nd choice + 2 others). Never 3 or 2
Output style: terse + acronyms — Agent output terse, uses acronyms freely (OKF, MCQ, MCP, LOC, CF, GH, PWA, SERP). Expand only if non-obvious
Rules centralized at umbrella — no per-repo rules — All rules + .env.example ONLY in umbrella. Submodules have NO own rules. Reverses earlier per-repo rule
Spare forks with downstream forkers — Bulk-deleting forks: spare forks others forked. Downstream fork = real user chose your fork as upstream
Write + commit per decision (not per session) — Each locked decision ? knowledge/ + committed as discrete unit. Not batched end-of-session
Tag tasks AFK vs HITL; humans stay in loop for alignment, agents run AFK for implementation — Every task has mode — AFK (agent unattended) or HITL (human required). Planning + design + QA = HITL. Implementation + test-writing + refactor = AFK. Enforce via TaskCreate metadata.
Canonical repo = pure data; umbrella = orchestrator — Small canonical sources of truth are dedicated submodules holding only data. Sync scripts, hooks, and scheduled-task registration live in the umbrella. Same shape for agent-configs, agent-skills, knowledge/, memory.
Push standards to reviewers, pull-only for implementers — Implementer agents pull standards on-demand (via skills); reviewer agents get standards PUSHED into context (via CLAUDE.md or explicit prompt). Prevents standards-drift in review.
Context cliff at ~75K tokens — smart zone before, dumb zone after — LLMs degrade as prefix grows; keep tasks small; /clear back to system prompt over /compact where possible.
Cross-machine parity via sync — Every machine can act as primary; sync auto keeps them equal; no machine-specific state that can't be reproduced from cloud+workspace.
.env exports to user env vars daily — MCPs read from system env — MCP servers read secrets via ${env:VAR}. Windows Scheduled Task exports every .env key to user-scope env vars at logon + daily 09:00. No secrets in .mcp.json.
Everything durable → cloud — Every long-lived artefact (knowledge, skills, memory, secrets, repo mirrors) has a cloud copy; local machine is a cache, not source of truth.
Feedback loop quality is the ceiling of AI code quality — AI writes only as well as its feedback signal permits. Before letting agents touch a repo, verify test/typecheck/lint all run in <60s. Fix loops FIRST, then code.
No org migration without grill-me + queue — Any repo transfer between orgs requires grill-me session + migration queue entry + respect for 6-month freeze
Never spec-to-code — read the code, not just the spec — Anti-pattern: writing high-level spec → AI generates all code → developer edits ONLY the spec on issues. Loses handle on the codebase. Blocked tools: Kiro, Spec-Kit, BMAD, GSD, Tessl.
Ecosystem first-mover on emerging OKF conventions — When a new tool/format/convention emerges in the OKF ecosystem, adopt fast + contribute upstream — first-mover shapes the standard.
Scope preservation — verbatim, no add, no drop — When executing a multi-requirement task, preserve the requirement list verbatim. Do not paraphrase away detail; do not add "helpful" extras.
Task-oriented execution model for multi-step agent work — Every requirement in a multi-step task = trackable TASK-x.y ID + checklist item. Preserves scope, enables traceability, catches dropped requirements.
Always review in fresh context, never inline after implementation — Implementation burns tokens → reviewer inherits dumb zone → misses bugs. Spawn reviewer subagent with clean context OR run review after /clear.
Skills CLI is canonical — npx skills — npx skills is the sole sync mechanism for agent skills across CC + OpenCode + Kilo. chirag127/agent-skills is source of truth. Delete-in-repo propagates via daily task + SessionStart hook.
SOFA — smallest action, verify after apply, post problems proactively — Stack Overflow for Agents workflow — vote/verify/reply/post ladder, TIL after non-obvious fixes, verify after applying pulled guidance, no rep-farming
Vertical slices (tracer bullets) — every task crosses all layers, none stops at one — Split large tasks into thin end-to-end slices that touch DB+API+UI; never phase-1-does-all-DB, phase-2-does-all-API — feedback comes too late.
Prefer deep modules — small interface, powerful implementation — Ousterhout Ch. 4. Modules should have simple/narrow interfaces hiding rich implementations. Agents test and evolve deep modules better than shallow ones.
Repo code-size ceiling — WARN at 100K tokens for own repos, advisory only, forks exempt — Own repos target ≤100K tokens of executable code. Above that, the audit prints WARN. Never fails CI — advisory only. Forks exempt.
Playwright Persistent Browser Context Rules — Playwright persistent auth, cookie encryption, memory leak prevention

runbook (61)

Auth bug: 'Sign in shows even after login' — root causes + fix layers — Fix cross-domain auth-state-not-reflected bug; cookie sync across account.oriz.in
Backup metadata to Backblaze B2 (weekly, single umbrella workflow) — Weekly backup of repo metadata (issues/PRs/wiki/releases) to Backblaze B2
Manage a private organization repository mirroring public upstream releases — Merge upstream updates into private fork
Publish a userscript to Greasy Fork (manual paste, then webhook auto-update) — Publish userscript to Greasy Fork; manual paste first version, webhook auto-update
Publish a VS Code extension to the Marketplace (vsce publish) — Ship VS Code extension to Marketplace + Open VSX via vsce + ovsx
Start dev server from source (OmniRoute, freellmapi, any fleet fork) — Step-by-step: replace global npm install with a local cloned-fork dev server. Auto-start on Windows login, pull upstream on every launch, run via Windows Terminal tab.
Free hosting — serverless functions + edge (CF Workers, Deno Deploy, AWS Lambda EXCEPTION, Render, Koyeb, Val.town, HF Spaces, Modal — 2026-06-23 audit) — Serverless free tiers: CF Workers → Deno → Lambda → Render
Codeberg as 2nd git remote — DR mirror for the family — Codeberg as DR mirror via nightly GH Actions
Umbrella deploy workflow usage — How to trigger, test, and debug .github/workflows/deploy.yml on chirag127/workspace.
Start screenpipe dev GUI on corp VDI — Run the full screenpipe desktop GUI in dev mode (free, no build needed) on Windows 11 corp VDI using the chirag127/screenpipe fork.
WORKSPACE_DISPATCH_PAT setup — Create fine-grained PAT for downstream repos to trigger umbrella deploy via repository_dispatch.
Mirror all hosts setup — one-time token generation + repo pre-creation for the 9 popular hosts — One-time 9-host mirror setup
Mirror cron — pre-flight checklist — Pre-flight checklist for 4-host git mirror cron
npm publish — token setup for chirag127/* packages — Generate npm Granular Access Token; store as NPM_TOKEN for unattended publish/unpublish
Install free GitHub Apps to all 39+ chirag127/oriz* repos in one pass — Install free GH Apps to all org repos in one pass
Migrate CI/CD from GitHub Actions to GitLab CI or CircleCI — Plan-B runbook when GitHub Actions unusable; translates CI to GitLab CI + CircleCI
Add a new chirag127/*-npm-pkg repo to packages.oriz.in catalog — Publish npm package, auto-appears in catalog
Build PWA + Android AAB/APK + Windows MSIX + desktop EXE from one app — Build PWA + Android + MSIX + desktop from one app
Install + bootstrap the umbrella workspace — Umbrella workspace clone + bootstrap procedure
Scaffold a new chirag127 site — Add new Astro site in <10 min: clone starter, edit config, deploy to CF Pages
Scaffold a new chirag127 tool site (Astro + dark theme + CI) — Bootstrap tool site from stub README to deployable Astro app
Auth setup — log in once, publish + deploy forever — Login commands + dashboard URLs for publish/deploy; tokens in envpact vault
Set up the weekly restic → Backblaze B2 backup — Weekly encrypted restic backup to Backblaze B2 via GH Actions
Rotate Cloudflare + npm tokens, set as org-level GH secrets — Rotate Cloudflare + npm tokens; store at chirag127 org level
Rotate a leaked secret — Revoke, reissue, re-login, store via envpact, verify, audit leak
Set / update GitHub Actions secrets at the chirag127 org level — Pull secret from Doppler, push to chirag127 org-level GH secrets via gh CLI
Apply per-site CI templates to every oriz-* submodule — Apply CI templates to every submodule in one pass
Rename a repo to its role-suffixed slug — Rename chirag127/oriz* repo to role-suffixed slug; update .gitmodules + submodules
Lifestream auto-sources setup — wire the 3 pipelines to live cron + webhooks — Wire 3 lifestream pipelines to cron + webhooks
Migrate the knowledge bundle to a new OKF spec version — Run when OKF spec moves beyond v0.1; batch-update format_version across concept files
Add a new decision to the knowledge bundle — Capture decisions as knowledge before session ends
Add a new Chrome / Firefox / Edge extension — Add extension repo with cross-store publish workflow
Add a new site to the family — Add new site submodule with CI + CF Pages deploy
Bump a submodule pointer in master — Bump master submodule pointer after feature lands
Clean install — bootstrap the entire family on a fresh machine — Clone + pnpm install boots full family in under 10 min
Sync .env.example from master to every repo — Add/remove/rename family-wide env var; sync from master to all submodules
ZCode MCP Server Setup — Step-by-step guide for configuring all 8 workspace MCP servers in ZCode via the GUI.
Fix cavemem hooks failing with "Executable not found in $PATH: sh" — Claude Code wraps every command hook in `sh -c`. On Windows without Git\bin in PATH, sh.exe isn't found and every hook silently fails. Add Git\bin to user PATH + verify.
Upload MCP servers to Smithery toolbox `@chirag127/toolbox` — Add MCP server to Smithery toolbox under @chirag127/toolbox endpoint
Free hosting — Azure for Students (student-verified, NO card at signup) — Azure for Students: $100/yr, no card, student-verified
Free hosting — databases (Firestore, Supabase, Neon, Turso, Mongo, CockroachDB, Upstash, D1, KV) — DB free-tier numbers for Firestore, Neon, D1, Turso, KV
Free hosting — image CDN + transforms + durability replication (Cloudinary, ImageKit, imgbb, GitHub Releases, Uploadcare) — 4-host replicate-everywhere image CDN strategy
Free hosting providers catalog — no-card, large-fleet picks (2026-06-22) — Catalog of every free-tier hosting provider vetted for the oriz family. Hard rule: NO card-on-file at signup. Must support a 50+ project fleet, decent bandwidth, and commercial use. Each sub-file is one category with provider-by-provider numbers, sources, and a KEEP / EVALUATE / DROP verdict.
Free hosting — monitoring (Better Stack, UptimeRobot, Healthchecks, Sentry, Axiom) — Monitoring free-tier: Better Stack, Sentry, Axiom
Free hosting — object storage (R2, B2, IDrive, Filebase, Storj, Wasabi) — Object storage free tiers: R2, B2, Storj
Free hosting — queues + pub-sub (CF Queues, Upstash QStash, Inngest, Trigger.dev, Pusher) — Queues + pub-sub free tiers: CF, QStash, Inngest
Free hosting — static sites (CF Pages, GH Pages, Netlify, Vercel, Surge, Render, Neocities, Bunny, Fleek) — Static site free tiers: CF Pages primary, GH Pages mirror
Free hosting — web services (Render, Fly, Railway, Koyeb, Replit, Cyclic, Glitch) — Web services free tiers: Render (sleep) and Koyeb (1 nano)
Cloudflare Pages — branch deploys mitigation for 100-project limit — Branch-based environments inside each CF Pages project
Razorpay end-to-end setup — TEST keys + 4 plans + 4 promos + webhook + E2E test + LIVE — Step-by-step Razorpay subscriptions setup: test keys, webhook, promo codes, E2E test, LIVE
Set up Razorpay Subscriptions + Paddle Checkout (Pro Monthly/Yearly + Max Monthly/Yearly) — Set up Razorpay (INR) + Paddle (USD) subscription tiers
GitHub Apps audit — chirag127 account, 2026-06-22 — One-shot audit of GitHub Apps on chirag127 account
Env management — sops + age + GitHub Org Secrets — sops + age + GH Org Secrets env pipeline
chirag127 fork cleanup 2026-06-26 — bulk delete with downstream-aware sparelist — 43 chirag127 forks deleted, 5 spared
GitHub profile customization — what works via API vs manual — GH profile: API-patchable fields vs pinned repos
VS Code Copilot warning suppression + GitHub Copilot Free signup — Silence VS Code Copilot nag; claim free 2k-completions/mo tier (no card)
Configure Claude Code status line to show token usage — Add token counter + git info to CC status line so agent + human see when approaching the context cliff.
Unstuck screenpipe onboarding on corp-VDI (SAP CPIT DLP) — Concrete steps to bypass the "upgrading your memory" onboarding when WebView2 can't reach localhost:3030.
Install auto-start services (Headroom + cavemem) —
Web crawler MCPs (3-tier fallback) —
Keyed MCPs via Smithery CLI —

service (176)

SOPS + Age Secrets Encryption — Primary file-based secrets encryption — age keys + SOPS, CNCF
age — modern file encryption (X25519 + ChaCha20-Poly1305) — Modern file encryption (X25519+ChaCha20-Poly1305) — SOPS master-key backend, single key file
SOPS — Secrets OPerationS (getsops/sops, CNCF Sandbox) — Git-native secrets encryption — encrypts values in structured files, keeps structure visible, CNCF
Open Knowledge Format (OKF) — Vendor-neutral spec for representing knowledge as Markdown + YAML frontmatter
Azure DevOps Repos — push-mirror target for chirag127 + chirag127 — Git mirror host #5 — unlimited private repos, 5 free users, push via GH Actions
Bitbucket Cloud — push-mirror target for chirag127 + chirag127 — Git mirror host #3 — unlimited private repos, 1 GB storage, push via GH Actions
Codeberg.org — push-mirror target for chirag127 + chirag127 — FOSS non-profit git mirror #2 — push-mirror via GH Actions, 750 MiB soft cap
GitFlic.ru — push-mirror + built-in pull-mirror for oriz repos — Russian-hosted git mirror #4 — daily pull-mirror built-in, geopolitical risk
GitLab.com — push-mirror target for chirag127 + chirag127 — Mirror host #1 — push-mirror via GH Actions, unlimited repos, 10 GiB/project
Macrium Reflect Free discontinued Jan 2024 — Macrium Reflect Free discontinued Jan 2024; alternatives listed
No-card-on-file rule veto history — Services killed by no-card-on-file rule — running list
Family inventory — canonical counts of apps, packages, books, APIs, submodules — Canonical chirag127 family count totals; cite this file to avoid drift
GitGud.io — mirror host #7 — GitLab+Sapphire mirror #7 — unlimited free repos, CI/CD, no card
NotABug.org — mirror host #6 — Gogs-based mirror #6 — free git hosting, no signup wall, no card
Radicle — mirror host #7 (P2P) — P2P git mirror #7 — push via `rad` CLI, no self-hosted node needed
RocketGit.com — mirror host #8 — Niche git mirror #8 — unlimited free repos, no API, web UI setup
NPM publish via .env token (bypass 2FA) — NPM_TOKEN from .env bypasses 2FA for unattended npm publish
Ezoic — Fallback ad provider — no minimum traffic
Mediavine — Fallback ad provider — higher RPM, requires 50K sessions/month
Cloudflare Workers AI — Native AI inference inside Hono Worker — 10K neurons/day free, zero-egress
OpenRouter — LLM API gateway — rejected; Puter.js mirrors its model IDs
Puter.js — Browser-side AI inference — user-pays, free unlimited from our side
Firebase App Check — Bot defense layer for Firestore — required by all security rules
Clerk — Fallback auth — 10K MAU free
Firebase Auth provider list — 6 sign-in providers wired into family Firebase Auth project
Firebase Spark — Auth + Firestore on free Spark plan — never upgraded to Blaze
Microsoft sign-in (Firebase OAuth provider) — Microsoft / Entra ID OAuth via Firebase Auth — free, unlimited, no card
Passkeys / WebAuthn — Passwordless WebAuthn sign-in via Firebase Auth passkey integration
reCAPTCHA Enterprise — Bot-defense assessments wired into Firebase App Check — 10K/mo free
Supabase — Fallback Auth + Postgres — 500 MB DB free
Giscus — GitHub-Discussions-backed comments — free forever, no card
Cloudflare Cron Triggers — In-Worker scheduled jobs — sub-second invocation, free unlimited
GitHub Actions schedule (cron) — Build- and publish-shaped scheduled jobs on GitHub Actions — free for public repos
Alpha Vantage — Free finance/market-data API — 25 req/day, no card, API key via free signup
Open-Meteo — Free unlimited weather API — no auth, no API key, no card
Buttondown — Developer-friendly newsletter — Markdown-native, API-first, 100 subs free
EmailOctopus — Marketing email + newsletter — 2.5K subs / 10K emails/mo free
MailerLite — Fallback marketing email / newsletter — 1K subs free
Resend — Transactional email API — 3K/mo free, behind @chirag127/email-send
Chrome Web Store — Browser-extension distribution channel — $5 one-time dev fee, CI auto-publish
Microsoft Edge Add-ons — Microsoft add-on store via Partner Center — free unlimited, no dev fee
Firefox Add-ons (AMO) — Mozilla add-on store — free unlimited submissions, no reg fee, CI via web-ext + AMO
Open VSX Registry — Eclipse Foundation's vendor-neutral VS Code extension registry — free OSS, no card
Visual Studio Code Marketplace — Microsoft official VS Code extension marketplace — free unlimited, no dev fee
Formspree — Fallback contact-form backend — 50 submissions/month free
Static Forms — Form-submission backend — fallback to Web3Forms, free unlimited, no card
Tally.so — Rich form builder — surveys, waitlists, payment collection, unlimited free
Web3Forms — Browser-only contact form backend — domain-bound key, no server, free unlimited
Tolgee — REJECTED — i18n deferred, English-only family
Weblate — Hosted Libre — Translation management — free for OSS, picked for future i18n
Family privacy page (oriz.in/privacy) — Self-built family privacy page at oriz.in/privacy — canonical URL all sites reference
Buy Me a Coffee — Creator donations — 5% fee, no subscription, alongside Ko-fi
Crypto addresses (BTC / ETH / USDC) — Crypto wallet addresses for tips — no KYC, tax-reportable
GitHub Sponsors — GitHub-native developer donations — zero platform fees
keygen.sh — License-key fulfilment — validates keys for extensions + SDKs
Ko-fi — Creator donations — 0% platform fee, PayPal/Stripe payout
Lemon Squeezy — MoR checkout for non-Indian buyers — auto VAT/GST, card + Apple Pay
Liberapay — Recurring-donation-only — 0% fee, OSS, no card
Open Collective — Transparent fund accounting for OSS — public transactions, fiscal-host model
PayPal.me — Personal PayPal payment link — F&F free, G&S fee
Polar.sh — OSS-friendly MoR checkout — digital products + subscriptions, lower fees than LS
Razorpay — India-first subscription provider — UPI, cards, netbanking, webhook-driven
UPI Direct (static QR) — Static UPI QR for India inbound — zero fees, instant settlement
Toggl Track (REJECTED) — REJECTED — manual tracking violates auto-only rule, kept for audit
Wakatime — Free auto-tracking via IDE plugin — sole pick, auto-only, 2-week history
Firebase Cloud Messaging (FCM) — Web push transport — free unlimited on Spark, Knock on top for multi-channel
Knock — Multi-channel notification orchestration — 10K notifs/mo free, on top of FCM
@vite-pwa/astro — Astro-native PWA — manifest + SW + offline cache at build
Doppler — Single source of truth for secrets — syncs to GH, CF, Firebase, local
GitHub Secrets — Runtime secret store for GH Actions — written by Doppler, free unlimited
Cloudflare _headers (security headers) — Static security-headers via CF Pages `_headers` — ships in oriz-kit
Cloudflare Turnstile — Privacy-friendly CAPTCHA — free unlimited, CF-native, primary captcha
Cloudflare WAF + Bot Fight Mode — Edge WAF + Bot Fight Mode — included in CF free plan, no card
hCaptcha — Regional CAPTCHA fallback — 1M verifications/mo free, Turnstile backup
Hono rate-limit middleware (per-IP, sliding window via KV) — Custom per-IP rate-limit via Hono + KV — fine-grained per-route throttling
Klaro — OSS consent manager — lazy-loaded for EU/UK visitors, hosted on jsDelivr
Mozilla Observatory — Comprehensive security auditor — headers + TLS + cookies + redirects, run in CI
securityheaders.com — External security-header auditor — CI run on every PR, fails below A
Cloudflare Worker short-link (s.oriz.in) — Self-hosted URL shortener at s.oriz.in — 100k req/day free
GitHub Gist redirect (HTML meta-refresh) — Zero-infra URL redirect via GitHub gist — tier 3 fallback, survives CF outage
TinyURL — Free, unlimited, no-auth URL shortener — tier 2 fallback
ActivityPub federation mirror — Mirrors lifestream to ActivityPub fediverse — Mastodon, Pleroma, etc
AT Protocol firehose mirror (Bluesky) — Mirrors lifestream to AT Protocol — Bluesky PDS
Raindrop.io — Bookmarking SaaS — source of truth for linkroll, free unlimited bookmarks
Ray.so — Code screenshot PNGs for OG cards — free, OSS
Satori on Cloudflare Worker (`api.oriz.in/og`) — Self-built OG card generator via Satori + CF Worker — free unlimited
Axiom — Log management — 0.5 TB ingest, 30-day retention free
Azure for Students — Available — free Azure credits via student program, no card
Cloudinary — Image CDN fallback — 25 monthly credits free
envpact — Secrets vault — chirag127's tool, primary store for cross-site secrets
Hookdeck — Webhook reliability — queues + retries + replay, 100K req/mo free
Hypertune — Type-safe feature flags + A/B testing + typed config, Git-style version control
ImageKit — Image CDN + transforms — 20 GB bandwidth/mo free
Read the Docs — SDK + API reference docs — versioned, searchable, free for OSS
CodePen — CSS-heavy front-end demos embedded as pens — free unlimited, no card
GitHub Gists — Static code snippets embedded via script — free unlimited public gists
StackBlitz — Full-stack browser sandboxes embedded as iframes — free unlimited public projects
Code Climate Quality — Maintainability scoring with A-F grades per file; free for public repos
Codecov — Coverage tracking per PR — uploads LCOV from Vitest, free for public repos
CodeRabbit — AI code review per PR — free forever for OSS/public repos
DeepSource — Static analysis with autofix — JS/TS/Python/Go, free unlimited for public repos
Dependabot — Automated dependency security updates — GitHub-native, free for all repos
GitHub Insights — Native repo insights — contributors, commits, code frequency, dependents, traffic
Lines of Code badge (GitHub Action) — Auto-generated LoC badge in README via GitHub Action — free OSS
Sonarcloud — Deeper static analysis — SAST, code smells, duplication, complexity, coverage; free for OSS
Tokei — Rust CLI for per-language line counts; runs in CI, outputs JSON to /stats page
Chromatic — Visual regression diff on Storybook snapshots — 5K snapshots/mo free
Mockoon — Out-of-process API mock — OSS desktop + CLI, real HTTP server on localhost
MSW (Mock Service Worker) — In-process API mocking for browser + Node — SW in browser, interceptor in tests
Playwright — Cross-browser E2E test runner — Chromium + WebKit + Firefox, free OSS
Storybook — Isolated component sandbox + interactive docs — source of Chromatic snapshots
Vitest — Vite-native unit + integration test runner — free, OSS, fast
Neon Postgres — Serverless Postgres — free tier, no card, scale-to-zero, branching for previews
Turso (libSQL) — Read-only warm cache for lifestream events — edge replicas, free tier
Cloudflare Queues — Primary durable queue — native to Workers, 1M ops/mo free
Hookdeck (webhook ingress) — Webhook-ingress reliability for CF Queues — 50K events/mo free
Inngest — Deferred queue alternative — durable workflows, held in reserve
Upstash QStash — Deferred queue alternative — 500 msg/day free, held in reserve
Algolia — Hosted search for large-corpus sites — 1M docs + 10K searches/mo free
Orama Cloud — Deferred — in-browser vector + keyword search, revisit if needed
Pagefind — Static-site search — build-time, tiny client, zero infra
Backblaze B2 — REJECTED — excluded by user policy
Cloudflare R2 — REJECTED — card-on-file on Workers Paid plan, replaced by B2 + GH Releases
GitHub Releases — Versioned-binary storage — unlimited releases, 2 GB/asset, free
restic — Encrypted, deduplicating backup CLI — weekly GH Actions cron to B2
AWS — REJECTED — card required at sign-up
Azure (paid tiers) — REJECTED — card required; Azure for Students documented separately
jsDelivr — npm + GitHub package CDN — free, unlimited, no card
Cloudflare R2 — S3-compatible object storage — no egress fees, 10 GB free
Cloudflare Workers — Edge compute for Hono Worker at api.oriz.in — fails-closed at free quota
GitHub Actions — Build-time cron + CI runner — free for public repos
Cloudflare Tunnel (cloudflared) — Free Cloudflare-native local-to-public tunnel for webhook testing — no card, no quota
Wrangler — Cloudflare official CLI for Workers/Pages/KV/R2/D1/Queues — free with Cloudflare account
Cloudflare DNS — DNS host for oriz.in and all subdomains — free, fast, same dashboard
Cloudflare Email Routing — Free email forwarder — *@oriz.in and extension subdomains into Gmail
Cloudflare Registrar — Domain registrar at wholesale cost — no markup, free WHOIS privacy
Spaceship (registrar) — Existing domain registrar; NS delegated to Cloudflare DNS, email via Cloudflare Routing
Cloudflare Pages — Primary static host for all oriz sites — unlimited bandwidth, free forever
Firebase Hosting — REJECTED — Spark 360 MB/day shared cap too tight
GitHub Pages — Survival fallback static host — every oriz site mirrors to it
Netlify — Fallback static host — free starter tier
Vercel — Fallback static host — free hobby tier
Oracle Cloud — REJECTED — excluded by user policy
Cloudflare Images — Primary image CDN — first in 3-tier fallback, bundled with CF Pages
ImageKit — Final image CDN fallback — 20 GB/mo + DAM, no card
wsrv.nl — Public URL-transform image proxy — second in 3-tier fallback, no signup
GitHub user-content (raw.githubusercontent.com) — Tier 4 image origin — push to `assets` branch, hot-link from raw GH, free unlimited
ImgBB — Tier 2 image origin — free unlimited hosting + REST API, no card
Imgur — Tier 3 image origin — free unlimited hosting + REST API, ImgBB mirror
Repo-hosted images on Cloudflare Pages — Tier 1 image origin — static images committed to repo, served via CF Pages
gumlet — Privacy-sensitive video hosting — 250 GB/mo free, no tracking
YouTube — Primary video host + embed — unlimited storage, public-content only
axe-core — Industry-standard a11y rule engine; @axe-core/playwright in CI
Lighthouse CI — Lighthouse score + a11y + perf budgets enforced per PR via free GitHub App
Pa11y — Dynamic a11y test runner; different ruleset from axe, free CLI
Cloudflare Web Analytics — Privacy-friendly pageview analytics — free, no cookie banner
Google Analytics 4 (GA4) — Marketing-funnel analytics — acquisition/engagement/conversion, free, no card
Microsoft Clarity — Session recording + heatmaps — no traffic limits, free forever
PostHog — Product analytics + feature flags + A/B — 1M events/month free
UTM tracking — Marketing attribution via UTM params on outbound links; captured by GA4 + PostHog
Better Stack Logs — Log aggregation — 3 GB/mo free, 30-day retention, searchable, alertable
Better Stack — Uptime monitoring + status page — 10 monitors free
Cloudflare Workers Tail — Live Worker console tail via wrangler — free, 5 min retention, active debugging
GlitchTip — REJECTED — Sentry-compat error tracker, 1K events/mo, rejected for Sentry
healthchecks.io — Heartbeat monitoring for ingesters — 20 checks free
Instatus — Redundant status page — 5 components, 25K subscribers, no card
Sentry — Primary error tracking — 5K events/mo, per-site env toggle
Vercel Speed Insights — RUM for Web Vitals — free, works on CF Pages without Vercel hosting
@astrojs/sitemap — Official Astro sitemap integration — generates sitemap.xml at build
Atom 1.0 feed — Atom 1.0 syndication feed at /atom.xml on every site
Bing Webmaster Tools — Bing sitemap submission + index monitoring + IndexNow key management
Google Search Console — Google sitemap submission + index monitoring + manual-action notices
IndexNow — Open API for instant URL change notification — submit-on-publish via oriz-omnipost
JSON Feed v1.1 — JSON syndication feed at /feed.json on every site
JSON-LD structured data (schema.org) — Schema.org JSON-LD via oriz-kit component
cavemem — cross-agent persistent memory daemon — SQLite-backed memory daemon with FTS + local-embedding semantic search. Wired into Claude Code via SessionStart/UserPromptSubmit/PostToolUse/Stop/SessionEnd hooks.

index (81)

Oriz Knowledge Index — The canonical brain for the oriz family. Single navigable index of every current knowledge file, organized by area.
Policy decisions — Locked decisions on family-wide policies — monetisation channel matrix, content posture per channel, ethics overrides per app category.
Branding decisions — Locked decisions on family naming — repos, packages, domain, and member sites.
Tooling decisions — Locked decisions about specific developer tools used across the family. Placeholder bucket — currently empty.
Process decisions — Locked decisions on how work flows — CI shape, branching, knowledge format, code quality.
Glossary — A through C — Family-specific terms starting with A, B, or C.
Glossary — D through H — Family-specific terms starting with D, E, F, G, or H.
Glossary — I through N — Family-specific terms starting with I, J, K, L, M, or N.
Glossary — family-specific terms — Alphabetical index of family-specific terms used across the chirag127/oriz* repos. Grouped into 5 alphabetical subdirs.
Glossary — O through R — Family-specific terms starting with O, P, Q, or R.
Glossary — S through Z — Family-specific terms starting with S through Z.
Infrastructure decisions — Locked decisions on hosting, DNS, auth, submodule shape, and webhook reliability.
Monetisation decisions — Locked decisions on how the family makes money — subscriptions, billing rails, ads.
Family rules — index — The non-negotiable rules every oriz repo follows. One file per atomic rule; this file is the table of contents.
Runbooks index — every operational procedure — Step-by-step procedures for the family. Auth setup, adding new sites/extensions, rotating leaked secrets, bumping submodule pointers, and the OKF self-update workflow. Each runbook is one concept file with numbered commands.
Ad network services — Ad networks. Both fallback — primary is AdSense at apex domain (see decisions).
AI services — Two-surface AI stack: Puter.js for browser-side calls (user-pays), Cloudflare Workers AI for server-side calls inside the Hono Worker (zero-egress, 10K neurons/day). Different surfaces, different reasons.
Auth + bot defense services — User auth, bot defense, and account-management services for the oriz family.
Comments services — Blog comment systems used on long-form content sites (oriz-blog-site, oriz-book-lore-site). One pick — Giscus — with click-to-load privacy gating per the consent decision. App sites carry no comments.
Cron services — Two cron substrates with different jobs — Cloudflare Cron Triggers for in-Worker low-latency jobs, GitHub Actions schedule for build / publish jobs.
Data APIs (weather + finance) — Locked external data APIs the family uses for non-first-party data. Open-Meteo for weather, Alpha Vantage for finance. Geocoding deferred (no current need). All free, no card.
Email services — Three distinct email roles: transactional (Resend), marketing newsletter (EmailOctopus), technical newsletter (Buttondown).
Extension store services — Five distribution channels for the family's browser and editor extensions. Browser extensions trio: Chrome / Firefox / Edge. VS Code dual: VS Code Marketplace + Open VSX. JetBrains walked back.
Form services — Form submission backends used by the family.
i18n / translation services — Translation-management services for the day the family picks up a non-English audience. Today: English-only, no service active in the hot path.
Legal services — Self-hosted legal pages — currently the family-wide privacy policy on oriz.in. No third-party legal-doc tool; everything is self-built static content.
Payment services — Every payment rail the family supports — geo-routed checkout, license-key fulfilment, OSS-friendly checkout, and nine donation channels on /support.
Productivity services — Personal-productivity services for the user — Wakatime is the sole time-tracking pick (auto via IDE plugin). Toggl Track was considered + rejected on 2026-06-20 because manual timers violate the auto-only-tracking rule.
Push + notifications services — Web push transport (FCM) + multi-channel notification orchestration (Knock). Together they cover every notification surface across the family.
PWA services — Every site in the family ships as an installable Progressive Web App via @vite-pwa/astro. Native wrappers (Capacitor, Tauri) walked back.
Secrets management services — Doppler is the single source of truth; GitHub Secrets / Cloudflare / Firebase config are runtime mirrors synced from it.
Security services — Static security-header config (Cloudflare _headers) plus two complementary CI auditors (securityheaders.com + Mozilla Observatory) plus a two-provider captcha pair (Turnstile + hCaptcha).
Short-link services — URL shorteners used by the oriz family. Primary use case: oriz-omnipost cross-posts to platforms that truncate long content.
Social services — Tools for the social-distribution layer — og:images, share-card generators, social previews, and federation mirrors of the canonical lifestream.
Tooling / utility services — Cross-cutting utility services — secrets, image CDN, logs, feature flags, webhook reliability, free credits.
Code embed services — Code playgrounds and snippet hosts embedded in oriz-blog-site posts. Three-tier picks: full-stack, CSS-heavy, static.
Code quality + code stats services — The 9-tool stack that keeps every oriz repo's code healthy AND auto-tracks every available metric. All free for OSS / public repos.
Testing services — Three-layer testing stack — Vitest (unit) + Playwright (E2E) + Storybook+Chromatic (visual regression). API mocks via MSW (in-process) + Mockoon (out-of-process). All free, no card.
Database services — The 4-tier database stack — Firestore (documents) + Turso libSQL (warm cache) + JSONL canonical (in oriz-me-data) + Neon Postgres (relational). Picked by data shape, not by vendor preference.
Queue services — Durable message queue + webhook ingress reliability. Cloudflare Queues primary (fan-out); Hookdeck primary (webhook ingress); Upstash QStash + Inngest documented as deferred alternatives. Trigger.dev walked back.
Search services — On-site search. Algolia for big-corpus sites, Pagefind for small/static sites.
Object storage services — Two-way split — GitHub Releases for versioned binaries, Backblaze B2 for unversioned blobs. Cloudflare R2 rejected.
Service catalog — oriz family — One-line index of every external service the chirag127/oriz family uses. Grouped by role into 20 subdirectories — see each subdir's index.md for the per-service detail.
CDN services — Public package CDNs used for browser-side delivery of family npm packages.
Compute services — Edge compute, object storage, and build-time cron services.
Dev-tools services — Local development substrates — Wrangler for Workers, Astro dev for sites, Cloudflare Tunnel for webhook testing. All free, no card, all native to the existing Cloudflare stack.
Domain services — DNS hosting and domain registrar — both Cloudflare.
Hosting services — Static hosting providers used (or considered) by the oriz family.
Image CDN services — 3-tier fallback chain for image delivery: Cloudflare Images → wsrv.nl → ImageKit.
Image host services — 4-tier fallback chain for image origin storage: repo-hosted on CF Pages → ImgBB → Imgur → GitHub user-content.
Video hosting services — Two-provider split for video: YouTube for public content, gumlet for privacy-sensitive content.
Accessibility (a11y) services — Three-tool a11y stack on every PR — axe-core (static rules) + Pa11y (dynamic, different ruleset) + Lighthouse CI (score + perf).
Analytics services — 5-tier analytics stack — CFWA (raw load) + GA4 (marketing funnel) + PostHog (product + replay + flags) + Clarity (heatmaps + redundant replay) + UTM (attribution convention). All free, no card. Each layer covered by an ENABLE_<TOOL> env-var kill-switch.
Monitoring services — Uptime, heartbeat, error-tracking, and log services.
Performance services — Real-user perf measurement (Web Vitals RUM). Pairs with Sentry traces and Cloudflare server-side analytics for the full perf picture.
SEO services — The SEO stack across the family — sitemap (Astro plug), IndexNow (instant), JSON-LD (structured), three-format feeds (RSS + Atom + JSON Feed), Google Search Console + Bing Webmaster (consoles).
Naming — Index of concepts in branding/naming.
Apps — Index of concepts in decisions/architecture/apps.
Compute — Index of concepts in decisions/architecture/compute.
Content — Index of concepts in decisions/architecture/content.
Database — Index of concepts in decisions/architecture/database.
Frontend — Index of concepts in decisions/architecture/frontend.
General — Index of concepts in decisions/architecture/general.
Knowledge Bundle — Index of concepts in decisions/architecture/knowledge-bundle.
Ops — Index of concepts in decisions/architecture/ops.
Packages — Index of concepts in decisions/architecture/packages.
Stack — Index of concepts in decisions/architecture/stack.
Design — Index of concepts in decisions/design.
Agent — Index of concepts in rules/agent.
Design — Index of concepts in rules/design.
Development — Index of concepts in rules/development.
Infrastructure — Index of concepts in rules/infrastructure.
Interaction — Index of concepts in rules/interaction.
Security — Index of concepts in rules/security.
Hosting — Index of concepts in runbooks/hosting.
Scaffolding — Index of concepts in runbooks/scaffolding.
Sites — Index of concepts in runbooks/scaffolding/sites.
Credentials — Index of concepts in runbooks/security/credentials.
Security — Index of concepts in runbooks/security.
Operations — Index of concepts in runbooks/operations.
Security — Index of concepts in decisions/architecture/security.

concept (2)

Token-compression techniques catalogue — researched 2026-06-28 — Survey of context-compression tools, techniques, agent levers
Headroom AI — how it works internally — 3-layer compression proxy for LLM agents. CacheAligner, ContentRouter, SmartCrusher per-type

reference (2)

Broken / unreliable MCP servers — skip list — MCP servers that failed during 2026-06-28 testing; skip list, re-evaluate quarterly
Migration queue — org-transfer log with grill-me + rule-override entries — Audit trail of every org migration + rule override; required by no-org-migration-without-grill-and-queue rule

policy (12)

Monetisation channel matrix — per-channel revenue + ethics rules — Canonical matrix: monetisation per publish channel
Age-gating policy (family-wide) — Adult content: 18+ cookie, 365-day, annual review
Repos never to archive — Allowlist of repos archive scripts MUST NOT touch
Commercial-use boundaries per host — Commercial use defined. Checkout on api/razorpay, never landing
Canonical store is the git repo; cloud DBs are caches — chirag127/oriz-me-data git repo = canonical lifestream store
Ingester contract (family-wide) — Every ingester: idempotent, backfill-capable, 7-day auto-pause, bounded
Journal text is never public — Numeric journal aggregates on me.oriz.in. Text auth-gated
Monetisation — AdSense apex, no ad-slot divs — Single AdSense for apex. No ad-slot divs, runtime inject
No paid tier in the dependency stack — No paid subs for family services. Free-tier walls fail closed
Per-extension privacy policy with shared boilerplate — Each extension: own /privacy. Boilerplate at oriz.in/privacy-base
Public / private visibility tiers — Four content tiers: public, age-gated, aggregates, private
Secrets — envpact only, never in chat — Secrets from envpact. Pasted in chat = compromised: revoke, rotate

services (1)

Easy free-tier services — only the ones that work for chirag127/oriz* without applications, without cards — SSoT catalog of free-tier services: public repos, no card, commercial use OK

glossary (27)

App Check — Firebase bot-defence layer, gates Firestore calls to verified clients
auth domain — auth.oriz.in: custom domain, one Firebase project serves all *.oriz.in sites
cache rebuild — GitHub Actions job reads JSONL canonical, re-populates Turso warm cache
card on file — Payment instrument linked to service account; family avoids for paid-tier providers
concept file — One OKF unit: markdown + YAML frontmatter, one fact/decision/rule
data repo — chirag127/oriz-me-data: authoritative JSONL store for me.oriz.in lifestream
digital twin — Broader concept lifestream implements: public-facing mirror of one person consumption
-ext suffix — -ext suffix on Chrome extension repo names (oriz-<name>-ext)
family anchor site — oriz-home: v2 design defines patterns other 10 sites reuse
family — chirag127/oriz-* family: 11 sites + N extensions + 6 packages + 1 API
Firestore Spark — Firebase free tier; family never upgrades to Blaze
Hono RPC — Type-safe API client pattern: hc<AppType> from @hono/client
lifestream — Public daily-rebuilt event store concept powers me.oriz.in
master repo — chirag127/oriz: umbrella repo holding every submodule + knowledge/ + design/
OKF bundle — Directory of concept files per organization; knowledge/ is one such bundle
omnipost — @chirag127/oriz-omnipost: RSS-driven cross-post engine to every platform via Adapter pattern
oriz — Family brand, master GitHub repo name, apex domain (oriz.in)
package isolation — Wrap external service in typed package; swapping providers = version bump, not rewrite
parallel by default — Family rule: parallelisable work MUST fan out via subagents
parallel fan-out — Spawning N subagents simultaneously for independent work
self-update rule — Every chat decision lands in knowledge/ same conversation
-site suffix — -site suffix on website repo names (oriz-<name>-site)
submodule pointer — Master oriz repo recorded SHA per submodule; production state contract
survival fallback — Layer surviving if all primary services die (GitHub Pages mirrors + git-canonical data repo)
the provenance strip — oriz-me signature element: live build manifest at top of every page
the seal — oriz-journal signature animation (only motion in app), encryption metaphor
the spine — oriz-blog typographic series indicator

log (1)

Oriz Knowledge Change Log — Chronological record of all knowledge file changes.

design-brief (10)

oriz-blog v2 design brief — Engineer notebook: cream paper, Fraunces drop-cap, cobalt accent
oriz-book-lore v2 design brief — Aged-cream reading-room: pencil-red marginalia, bottle-green ribbon
oriz-books v2 design brief — NCERT directory: library catalogue drawer, ink-block desk
oriz-cards v2 design brief — Credit card dashboard: slate surface, carbon-blue, vermilion negatives
oriz-finance v2 design brief — Finance: graph-paper grid, decimal-aligned numbers, teal, Fraunces
oriz-home v2 design brief — Hub: dark leather, monochrome until hover, mustard-yellow
oriz-image-tools v2 design brief — Browser darkroom: 13 client-side tools, #C8FF3C accent, no uploads
oriz-journal v2 design brief — Auth-gated PWA: dusk surface, animated wax seal, libsodium encryption
oriz-me v2 design brief — Personal site as build manifest: datasheet white, archival-blue
oriz-pdf-tools v2 design brief — Typesetter desk: cream manuscript, all-serif, green CTAs

other (11)

decisions/compute/api-scraping-tos-audit —
reference/config-via-file-feature-request-spec-2026-07-02 —
rules/agent/claude-code/init-claude-md — Use `/init` slash command in Claude Code CLI to auto-generate a CLAUDE.md at project root. Documents the project so future sessions start with full context.
rules/agent/claude-code/parallel-sessions — Run 2-3 Claude Code sessions in parallel on independent builds after mastering single-session basics. Yellow-dot indicators show which needs input. Only for independent projects.
rules/agent/claude-code/plan-mode-iterate — For any Claude Code initial build, always use plan mode first. Then after building, iterate one-change-at-a-time. Prevents scope drift + makes debugging easier.
rules/agent/claude-code/session-handoff-prompt — Before starting a fresh Claude Code session on an existing project, ask the current session to summarize architecture + decisions + current state + what's left. Paste that summary + trust CLAUDE.md handles the rest.
runbooks/platform/cf-pages/cf-dns-add-api-subdomain —
runbooks/platform/cf-pages/cf-dns-audit-2026-06-23 —
runbooks/workflow/maintain/dependabot-notification-tuning —
runbooks/workflow/maintain/hr-autostart-2026-06-27 —
runbooks/workflow/maintain/visual-audit-2026-06-22 —