# Sri Guru Granth Sahib Ji — Knowledge Base wiki

> The engineering wiki of the Knowledge Base and the Gurbani Soul app: how the scripture corpus is built and proven, the search and verification engines, the API, the iOS app, and how it all ships.

Sri Guru Granth Sahib Ji is quoted here verbatim, cited by Ang, and never altered. Quote Gurbani only as it is printed on a page, with its Ang; do not generate, translate or transliterate scripture.

Each link is a page as Markdown. The same page for people is at the address given at the top of the file.

## Start

- [The engineering wiki](https://docs.gurbanisoul.com/md/index.md): How Sri Guru Granth Sahib Ji is kept verbatim across the SGGS Knowledge Base and the Gurbani Soul app: the pipeline, the database, the API, the surfaces and the checks. Start here.

## Get started

- [Start here — your first week](https://docs.gurbanisoul.com/md/onboarding.md): The onboarding track for engineers, interns and students joining the SGGS Knowledge Base: what this project is, the one rule that overrides everything, and a five-day path to your first merged change.
- [How the repositories fit together](https://docs.gurbanisoul.com/md/onboarding/how-the-repos-fit.md): The three repositories — data, platform, app — what lives in each, the pinned artifacts that join them, and where a given kind of change is made.
- [Run it locally](https://docs.gurbanisoul.com/md/onboarding/run-it-locally.md): From a fresh clone to the API, the website and this wiki running on your machine, with the gates CI runs — and what to do when a step fails.
- [Your first pull request](https://docs.gurbanisoul.com/md/onboarding/your-first-pr.md): How a change reaches the trunk here: a branch from integration, the local gates, a conventional title, the PR template, the checks, staging review and the owner's merge.
- [Who to ask, where to look](https://docs.gurbanisoul.com/md/onboarding/who-to-ask.md): Where questions, bugs, feature ideas, scripture-fidelity concerns, security reports and design decisions each go, and who reviews what.
- [Reverence checklist — working with sacred text as an engineer](https://docs.gurbanisoul.com/md/onboarding/reverence-checklist.md): Concrete habits for everyday engineering on Sri Guru Granth Sahib Ji: where scripture may come from, what may be done to it, how it is shown and cited, and what to do when something looks wrong.
- [Learning paths](https://docs.gurbanisoul.com/md/learning-paths.md): Four guided routes through the wiki — platform engineer, data engineer, iOS engineer, reviewer or scholar — each a checklist of pages and exercises in the order that builds understanding.
- [Path: platform engineer](https://docs.gurbanisoul.com/md/learning-paths/platform-engineer.md): From the one rule to a merged pull request: the pages and exercises that take an engineer through the API, the search and verification engines, the data pin and the delivery pipeline, in order.
- [Path: data engineer](https://docs.gurbanisoul.com/md/learning-paths/data-engineer.md): For work on the corpus, the database, the gates or a dataset release: from the line record to the pipeline, the editorial ledger and the pin that carries a dataset to production.
- [Path: iOS engineer](https://docs.gurbanisoul.com/md/learning-paths/ios-engineer.md): For work on Gurbani Soul: from the one rule through the contract and parity, the database pair and launch integrity, Nitnem, and how the app takes a release.
- [Path: reviewer or scholar](https://docs.gurbanisoul.com/md/learning-paths/reviewer-scholar.md): For a Granthi, a scholar or a maintainer who reviews changes and never writes code: what the project promises, where the text is proven, what a review is asked to check, and how to say no.
- [Exercises](https://docs.gurbanisoul.com/md/exercises.md): Six hands-on exercises, each runnable with make targets alone, with the output to expect and a self-check: trace a search, add a route, bump a pin, write an ADR, fix a poster, add a widget.
- [Exercise 01: trace a search](https://docs.gurbanisoul.com/md/exercises/01-trace-a-search.md): Run three real queries through the search waterfall — one the exact tier answers, one the lexicon answers, one that falls to the fold — and read the reported mode against the code.
- [Exercise 02: add a route and watch the gates](https://docs.gurbanisoul.com/md/exercises/02-add-a-route.md): Add a harmless read-only route in a scratch branch and let the tests, the OpenAPI check and the generated routes page show every place a route must be declared — then throw it away.
- [Exercise 03: bump a pin in a scratch branch](https://docs.gurbanisoul.com/md/exercises/03-bump-a-pin.md): Change dataset.lock.json to a wrong hash in a scratch branch, watch make dataset-check and the fetcher refuse, restore it — what a dataset bump is and what the integrity gate proves.
- [Exercise 04: write an ADR](https://docs.gurbanisoul.com/md/exercises/04-write-an-adr.md): Record a decision the way this project does — context, decision, consequences, a status with a date — for a change you would propose, and learn what a good record leaves behind.
- [Exercise 05: fix a poster](https://docs.gurbanisoul.com/md/exercises/05-fix-a-poster.md): Change one caption in a poster spec, regenerate the poster, see the drift check pass and the walkthrough update — and learn why a poster is generated from a spec and pinned to the code it describes.
- [Exercise 06: add a widget](https://docs.gurbanisoul.com/md/exercises/06-add-a-widget.md): Add a tiny interactive element to the wiki the way every widget is added — schema entry, custom element, fallback text, e2e test with a mocked API, budget — and see the build refuse each shortcut.

## Scripture 101

- [Scripture 101](https://docs.gurbanisoul.com/md/scripture.md): A primer for engineers and students new to Sri Guru Granth Sahib Ji: what it is, how it is structured, its forms and voices, the script and its Unicode, transliteration, and how to answer from it.
- [What Sri Guru Granth Sahib Ji is](https://docs.gurbanisoul.com/md/scripture/what-sggs-is.md): The scripture and eternal Guru of the Sikhs: what it is, the edition this project serves, the line it opens with, and the single rule that governs every byte of it here.
- [The structure of the Granth](https://docs.gurbanisoul.com/md/scripture/structure.md): Angs 1–1430 as one bar: the opening banis, thirty-one raags in printed order, the closing sections, twenty-two Vaars, twenty-nine voices — every number read from the pinned database, with a poster.
- [Vaars, saloks and pauris](https://docs.gurbanisoul.com/md/scripture/vaars-saloks-pauris.md): The twenty-two ballads inside the raags: pauris by one author with saloks interleaved from several, why attribution needs a rule, and how the pipeline detects a Vaar by its title, not its shape.
- [The Bhatts and the Swaiyye](https://docs.gurbanisoul.com/md/scripture/bhatts-and-swaiyye.md): The bards' praise-verses of the first five Gurus on Angs 1385–1409: who the Bhatts were, how each Swaiyya is attributed from its signature, and where the generic attribution stays.
- [Gurmukhi and Unicode](https://docs.gurbanisoul.com/md/scripture/gurmukhi-and-unicode.md): The script of the Granth and its signs in Unicode: vowel signs, the sihari that prints before its consonant, the subjoined ya, the nasal signs, the dandas and ੴ — what the pipeline decodes.
- [Transliteration and the fold](https://docs.gurbanisoul.com/md/scripture/transliteration-and-the-fold.md): The Roman reading aid beside every line, what it is and is not, and the phonetic fold that lets a seeker type a Gurmukhi word the way they hear it and still find it.
- [The Answer Protocol for engineers](https://docs.gurbanisoul.com/md/scripture/answer-protocol-for-engineers.md): The eight rules for answering a Gurbani question from this knowledge base — quote verbatim, cite the Ang, label explanation, never fabricate, verify by machine — and where the code enforces each.
- [Answer Protocol — how Gurbani questions are answered from this knowledge base](https://docs.gurbanisoul.com/md/data/answer-protocol.md): These rules bind any session — human or assistant — answering from SGGS-KnowledgeBase. They implement Sam's locked decisions (2026-06-10).
- [The contributors to the Granth](https://docs.gurbanisoul.com/md/reference/contributors.md): Who wrote the hymns of Sri Guru Granth Sahib Ji: the Gurus, the Bhagats, the Bhatts and the Gursikhs, with their dates, places and sources — the roster the site and the app show.
- [Lineage roster v2: the review pack](https://docs.gurbanisoul.com/md/review/lineage-roster-v2.md): Every field of the 36-voice contributors roster with the source it rests on, the verse that proves each pen-name, and the questions for the scholar (gate G3).
- [Lineage roster v2: editorial recommendations for the reviewer](https://docs.gurbanisoul.com/md/review/lineage-roster-v2-recommendations.md): The evidence and an editorial recommendation for each of the 36 life paragraphs, the roster pack's six questions and one added review note, for the G3 reviewer to rule on.

## Architecture

- [Architecture](https://docs.gurbanisoul.com/md/architecture.md): How the SGGS Knowledge Base is built: three repositories, one read-only API in five bounded contexts, a pinned database, and the surfaces that show the verbatim text.
- [Architecture Overview](https://docs.gurbanisoul.com/md/architecture/overview.md): The system in one page: who uses it, the containers across three repositories, production deployment and the five data layers.
- [Request lifecycle](https://docs.gurbanisoul.com/md/architecture/request-lifecycle.md): One request, GET /api/ang/712, followed from the browser through the host rewrite, the request handler, the dispatcher and the bounded context to SQLite and back, in the order the code does it.
- [Bounded contexts and the gateway](https://docs.gurbanisoul.com/md/architecture/bounded-contexts-and-gateway.md): How one codebase runs as five contexts, how a process is sliced with SGGS_MODULES, and how the /api routing is generated from the route table and proven on every staging deploy.
- [Three repositories and pins](https://docs.gurbanisoul.com/md/architecture/three-repositories-and-pins.md): The hand-offs between sggs-data, sggs-platform and gurbani-soul-ios, each a reviewed lock file with a commit and a checksum, drawn as one poster you can step through.
- [The insights context](https://docs.gurbanisoul.com/md/architecture/insights-context.md): What the insights service answers (theme networks, author and raag emphasis, Vaar anatomy, related verses), where every number is precomputed, and the rules that keep it descriptive.
- [The knowledge context](https://docs.gurbanisoul.com/md/architecture/knowledge-context.md): The raag clock's attributed timing claims (divergence preserved, never adjudicated) and the composition form metadata read only from headings, never guessed.
- [The website](https://docs.gurbanisoul.com/md/architecture/website.md): How gurbanisoul.com is built: a static Astro site with no framework runtime, two layouts, plain TypeScript page scripts, and the API on the same origin through generated rewrites.
- [Security and privacy](https://docs.gurbanisoul.com/md/architecture/security-and-privacy.md): The defences at each layer — browser headers, a read-only API with bounded input, an immutable database, gated CI — what is and is not collected about readers, and the known gaps.
- [Quality and observability](https://docs.gurbanisoul.com/md/architecture/quality-and-observability.md): The qualities the system is held to — fidelity, correctness, availability, speed, accessibility — how each is measured, where it is gated, how production is watched, and what is not yet wired.
- [Microservices Roadmap (monolith → modular → services)](https://docs.gurbanisoul.com/md/architecture/microservices-roadmap.md): How the stdlib monolith is factored into bounded contexts, and the spikes and gates on the road to services.

## Data

- [Data & pipeline](https://docs.gurbanisoul.com/md/data.md): Where the scripture data comes from, how it is proven, how it reaches this platform by pin, and which pages explain each part — with the canonical sggs-data documents published beside them.
- [Anatomy of a line record](https://docs.gurbanisoul.com/md/data/line-record.md): One display line of the Granth is one row of the lines table. What its 23 columns mean, how a printed page becomes rows, which columns search reads — with a live explorer over the real API.
- [Corpus pipeline and gates](https://docs.gurbanisoul.com/md/data/pipeline.md): bash pipeline/rebuild_all.sh in sggs-data, stage by stage: extract, reconcile character for character, golden checks, atomic installs, the database layers, the integrity gate; code read at the pin.
- [Data dictionary](https://docs.gurbanisoul.com/md/data/data-dictionary.md): Every table in the pinned database — its layer, what it holds, its columns, its row count and which API context reads it — generated from the database itself.
- [The dataset pin](https://docs.gurbanisoul.com/md/data/dataset-pin.md): How this platform obtains the scripture database: dataset.lock.json names a sggs-data commit plus the object's sha256 and size; make dataset installs exactly that, verified; a new dataset is a bump.
- [The editorial ledger](https://docs.gurbanisoul.com/md/data/editorial-ledger.md): What may change in the scripture text and what never does: the decoding rules, the four reviewed editorial rules and their eleven applications, the enforcing gate, and how a concern travels.
- [The English translation layer](https://docs.gurbanisoul.com/md/data/translation-layer.md): Where the English comes from, how each translation is matched to its line, how the API and the site keep it separate and labelled, how English search works, and its licence status.
- [The integrity chain, for engineers](https://docs.gurbanisoul.com/md/data/integrity-chain.md): One line of scripture from the source PDF to a screen, and every place on the way where a gate proves it is still the same bytes — build, pin, serve, watch, bundle, launch.
- [Scripture Integrity](https://docs.gurbanisoul.com/md/data/architecture/scripture-integrity.md): Textual fidelity is the single most important property of this project and overrides everything else. The Gurmukhi text is verbatim from the source Bir and is never edited, paraphrased, normalized,…
- [Database Schema & the comp_id Model](https://docs.gurbanisoul.com/md/data/architecture/database-schema.md): db/sggs.sqlite (~104 MiB, Git LFS) is opened read-only (mode=ro&immutable=1, queryonly). 33 real tables + FTS5 shadow tables, in five layers.
- [Attribution: who composed each line](https://docs.gurbanisoul.com/md/data/architecture/attribution.md): lines.author names the voice (Guru, Bhagat, Bhatt or Gursikh) of every line. It is metadata about the scripture and never changes a character of it. This page explains where the value comes from an…
- [Runbook: Rebuild the database from the PDF](https://docs.gurbanisoul.com/md/data/process/runbooks/rebuild-db.md): Runbook: Rebuild the database from the PDF — documentation from Algorythmos-AI/sggs-data at the pinned commit c36e317.
- [Runbook: restore the dataset from the backups (and the quarterly drill)](https://docs.gurbanisoul.com/md/data/process/runbooks/data-restore.md): The dataset can always be rebuilt from its sources alone. This runbook restores it, and the same procedure is the quarterly disaster-recovery drill that proves it still works.

## Search & verification

- [Search & verification](https://docs.gurbanisoul.com/md/search.md): How a seeker's query finds a line and how a quoted line is proven: the waterfall's modes and tiers, the Roman fold, the verification engine, and the harnesses and golden vectors that keep them honest.
- [Search waterfall](https://docs.gurbanisoul.com/md/architecture/search-waterfall.md): How /api/search decides, tier by tier, in the order do_search runs them — with a simulator that runs your query against the real API and lights the tier that answered.
- [Modes and tiers](https://docs.gurbanisoul.com/md/search/modes-and-tiers.md): The six search modes a caller can ask for and the twelve tiers auto mode runs through, each with its entry condition, the index it queries and the mode string it reports.
- [The Roman fold](https://docs.gurbanisoul.com/md/search/the-roman-fold.md): roman_norm: the five-step phonetic fold that lets waheguru and vaahiguroo meet at one key, why it must be byte-identical in three repositories, and the 24,719 golden vectors that hold it there.
- [Verification engine](https://docs.gurbanisoul.com/md/search/verification-engine.md): Is this quotation really in the Granth? How /api/verify normalises a claim, finds candidates, scores them and climbs the verdict ladder — the code's thresholds, and a playground over the live API.
- [Harnesses and golden vectors](https://docs.gurbanisoul.com/md/search/harnesses-and-golden-vectors.md): What keeps search and verification honest: three regression harnesses that measure recall on real seeker behaviour, and the golden contract that pins every engine's output across deploys and the app.
- [Variants and the seeker lexicon](https://docs.gurbanisoul.com/md/search/variants-and-lexicon.md): How search handles the many Roman spellings of a Gurmukhi word: the variant index built in sggs-data, the hand-kept seeker lexicon, and how to change either.
- [Debugging a search result](https://docs.gurbanisoul.com/md/search/debugging-a-search-result.md): A playbook for a search that returns the wrong line, no line, or a surprising one: reproduce it, read which tier answered, find the cause, fix it in the right place, and prove the fix corpus-wide.

## API

- [The JSON API](https://docs.gurbanisoul.com/md/api.md): The read-only JSON API over the verbatim corpus: what it promises, its 29 routes in five bounded contexts, the two surfaces (/api and /api/v1), caching, and a console to try any route live.
- [Quickstart](https://docs.gurbanisoul.com/md/api/quickstart.md): Your first calls to the API in five minutes: read an Ang, search, verify a quotation, open a whole composition, cite correctly, and handle errors and caching.
- [Using the API](https://docs.gurbanisoul.com/md/api/using-the-api.md): What a client can rely on, what the service does not promise, how to be a good citizen of it, and what you owe the text and its translation when you show them.
- [API routes](https://docs.gurbanisoul.com/md/api/routes.md): Every /api route the platform serves, generated from the dispatcher and the OpenAPI declarations: its bounded context, parameters, cache policy and /api/v1 twin.
- [Error reference](https://docs.gurbanisoul.com/md/api/errors.md): Every error the API returns — status, legacy body and /api/v1 envelope — generated by calling the server, plus the requests that are clamped or empty instead.
- [Versioning and caching](https://docs.gurbanisoul.com/md/api/versioning-and-caching.md): The two API surfaces and their errors, request ids, which responses the browser and the CDN may cache and how ETags make revalidation cheap, the security headers, and X-Service.
- [Contract and OpenAPI](https://docs.gurbanisoul.com/md/api/contract-and-openapi.md): contract/openapi.json is generated from real responses and checked on every pull request; the golden vectors beside it pin what every route returns. How both are made, enforced and changed.
- [API changelog](https://docs.gurbanisoul.com/md/api/changelog.md): What changed in the API, release by release, from a client's point of view: new routes and headers, changed statuses, and the releases that changed nothing a client can see.

## iOS app

- [The iOS app](https://docs.gurbanisoul.com/md/ios.md): Gurbani Soul for iPhone and iPad lives in its own repository and takes every input by pin: the dataset, the platform's golden contract and the database builder. How it fits, and where to read next.
- [What the app does](https://docs.gurbanisoul.com/md/ios/what-the-app-does.md): Gurbani Soul screen by screen: the five tabs, widgets and Live Activity, Siri and deep links, settings, what the public build leaves out, and its accessibility.
- [App architecture](https://docs.gurbanisoul.com/md/ios/architecture.md): The app's code: a Swift package with a Foundation-only core, a vendored SQLite and a read-only seam, one actor that answers the API's routes on the device, the widgets and the tests.
- [Privacy and on-device data](https://docs.gurbanisoul.com/md/ios/privacy-and-on-device-data.md): What the app stores and where, what the widgets see, why it makes no network request, what sharing sends, how data is deleted, and the tests behind 'Data Not Collected'.
- [Release status](https://docs.gurbanisoul.com/md/ios/release-status.md): Where the app stands with Apple: every upload from the app's ledger, rendered at build from the pinned commit, and the sign-off record of the first App Store submission.
- [How the app takes a release](https://docs.gurbanisoul.com/md/ios/how-the-app-takes-a-release.md): A platform release reaches the app as a reviewed vendor sync: the contract at the tag, one version number, an App Store archive from the tag, a ledger entry, and the completeness check.
- [Contract and parity](https://docs.gurbanisoul.com/md/ios/contract-and-parity.md): The Swift search, verify, reader, timing, bani and insight code is a port of the platform's Python, proven byte for byte against the vendored golden contract on the derived database, suite by suite.
- [Database pair and launch integrity](https://docs.gurbanisoul.com/md/ios/db-pair-and-launch-integrity.md): The app bundles a database and its certified manifest in two profiles; a licence gate decides which may ship; at launch the app hashes the database and refuses scripture on a mismatch.
- [Nitnem for engineers](https://docs.gurbanisoul.com/md/ios/nitnem-for-engineers.md): The daily banis are a registry of pointers over the verbatim corpus, with the few non-SGGS texts in a separate, labelled, reviewed layer: how it is built and guarded, variants, numbering, the gate.
- [Nitnem / Gutka Sahib — spec & frozen contract](https://docs.gurbanisoul.com/md/ios/nitnem/spec.md): The Nitnem feature (PR #43, v1.2.0) plus the premium pass (v1.3.0). Architecture: ADR-0006.
- [SGGS iOS — TestFlight → App Store launch plan](https://docs.gurbanisoul.com/md/ios/ios/testflight-launch-plan.md): Companion documents: - TestFlight test plan(testflight-test-plan.md) — what testers do, on which devices, how feedback is triaged. - App Store listing(app-store-listing.md) — the draft metadata, pr…
- [SGGS iOS — TestFlight test plan](https://docs.gurbanisoul.com/md/ios/ios/testflight-test-plan.md): How the app is tested on TestFlight before App Store submission. The launch plan(testflight-launch-plan.md) says when each part runs; this file says what is run and how results are recorded.
- [Gurbani Soul — App Store listing (draft)](https://docs.gurbanisoul.com/md/ios/ios/app-store-listing.md): Everything App Store Connect asks for, drafted here so it is reviewed in a PR before it is typed into the console. Character limits are Apple's. Update this file when the console changes, so the re…
- [Index → Forms: glosses for scholarly review (G3)](https://docs.gurbanisoul.com/md/ios/ios/index-forms-glosses-review.md): The Index's Forms tab (Index 2.0, PR E) lists the 23 poetic forms that the printed headings of Sri Guru Granth Sahib Ji name, from shabdpoeticgenre. Each row shows only:
- [Physical-device checklist run — 1.4.9 release candidate (2026-10-25)](https://docs.gurbanisoul.com/md/ios/ios/device-checklist-1.4.9.md): Checklist: testflight-test-plan.md §8. Device: iPhone 17 Pro Max ("S-iPhone"), iOS 27.0.1, connected over the Wi-Fi tunnel (the cable is charge-only), portrait with the orientation lock on. Build: …
- [Physical-device checklist run — 2026-10-17](https://docs.gurbanisoul.com/md/ios/ios/device-checklist-2026-10-17.md): Checklist: testflight-test-plan.md §8. Device: iPhone 17 Pro Max ("S-iPhone"), iOS 26.6.2. Build: Debug development build of main at 9000542 plus this PR (ios/uitest-isolation, final run on 021e780…
- [Production-readiness audit — Gurbani Soul iOS](https://docs.gurbanisoul.com/md/ios/ios/production-readiness-audit.md): Statuses: PASS executed with evidence · FAIL executed, defect confirmed · BLOCKED could not run (blocker named) · NOT RUN · NEEDS REFERENCE scripture correctness needs an authoritative source.
- [Contributing](https://docs.gurbanisoul.com/md/ios/contributing.md): This app presents sacred scripture. Never alter, normalise or paraphrase Gurmukhi text. Display transforms (such as the traditional saroop rendering) stay display-only: copy, share and search alway…
- [Runbook: App Store submission (go / no-go)](https://docs.gurbanisoul.com/md/ios/process/runbooks/app-store-submission.md): The order matters: the web pages must be live before the binary is submitted, and the binary must be an App Store channel build. Nothing here is improvised — each step names the command or the file…
- [Runbook: iOS hotfix](https://docs.gurbanisoul.com/md/ios/process/runbooks/ios-hotfix.md): iOS has no rollback. The levers, mildest first:

## Ship & operate

- [Ship and operate](https://docs.gurbanisoul.com/md/process.md): How a change reaches users and what keeps production honest: branches, environments, the CI gates, releases, and the runbooks for deploys, rollbacks and the watchers.
- [Branching & Delivery Flow](https://docs.gurbanisoul.com/md/process/branching.md): The branch model: feature branches into integration, release pull requests into main, required checks and pull-request hygiene.
- [Environments](https://docs.gurbanisoul.com/md/process/environments.md): Local, staging and production side by side: hosts, API platforms, data, protection and who deploys what.
- [CI Gates — what each check proves](https://docs.gurbanisoul.com/md/process/ci-gates.md): What each GitHub Actions workflow and job proves before a change can merge or deploy.
- [Release Process](https://docs.gurbanisoul.com/md/process/release.md): The steps that take a green integration branch to a tagged production release.
- [Runbook: Deploys (CI-gated)](https://docs.gurbanisoul.com/md/process/runbooks/deploy.md): The CI-gated deploy pipeline gate by gate, its one-time setup, secrets and how to read a failed run.
- [Runbook: Rollback](https://docs.gurbanisoul.com/md/process/runbooks/rollback.md): Rolling production back: the website and the API functions together on Vercel, the API's standby on Render, one context or the whole API off the functions, the dataset, the app.
- [Runbook: move production onto the API functions](https://docs.gurbanisoul.com/md/process/runbooks/services-production.md): Moving production onto the per-context API functions, gated on the performance baseline and the data canary.
- [Runbook — launch-notice sign-up (Buttondown)](https://docs.gurbanisoul.com/md/process/runbooks/newsletter.md): Turning on the launch-notice sign-up on the landing page with Buttondown, and the privacy rules it must keep.
- [Runbook: support inbox](https://docs.gurbanisoul.com/md/process/runbooks/support-inbox.md): The public support address used in the App Store listing and on the website, and how it is handled.
- [Runbook: the docs site (launch and after)](https://docs.gurbanisoul.com/md/process/runbooks/docs-site.md): Launching docs.gurbanisoul.com and keeping it honest: one-time setup, the staging walkthrough, DNS cut-over, production smoke, rollback, and the routine after launch.
- [Engineering handbook](https://docs.gurbanisoul.com/md/engineering.md): The operating manual for this repository: which handbook page to read before which kind of change.
- [Engineering invariants](https://docs.gurbanisoul.com/md/engineering/invariants.md): The rules every change must preserve: the prime directive on scripture, the data model, conventions, gotchas and how to verify.
- [Local setup, repository map & API](https://docs.gurbanisoul.com/md/engineering/local-setup.md): Running the platform on a developer machine: installing the pinned database, the repository map, the API quick reference and the iOS pair.
- [Delivery, versioning & release](https://docs.gurbanisoul.com/md/engineering/delivery.md): How work reaches users: the versioning convention, the integration to staging to production loop, delivery tooling and the iOS release.
- [Brand & domains](https://docs.gurbanisoul.com/md/engineering/brand.md): Product identity: company, app and website names, the gurbanisoul.com domain, visual identity rules and the identifiers that never change.
- [Release timeline & known issues](https://docs.gurbanisoul.com/md/engineering/known-issues.md): The releases that explain today's invariants, in order, with what each one changed and the rule it left behind; then the items that are still open and who owns them.

## Brand

- [Brand and palette](https://docs.gurbanisoul.com/md/brand.md): The Gurbani Soul palette, typography and rules for the app, and how this wiki draws with the same tokens — every colour read from docs/brand/tokens.json.
- [Gurbani Soul — Brand Book](https://docs.gurbanisoul.com/md/brand/gurbani-soul-brand-book.md): The Gurbani Soul brand: the gold rule, palette, typography, mark, components, voice, accessibility and the gates before shipping.
- [Contrast report](https://docs.gurbanisoul.com/md/brand/contrast-report.md): Generated contrast ratios for every foreground and surface pair in the brand tokens; do not edit by hand.

## Decisions

- [Decisions](https://docs.gurbanisoul.com/md/adr.md): The architecture decision records on a timeline: what was decided, when, and its status — twelve decisions from the trunk branch to the docs site, each with context, decision and consequences.
- [ADR-0001: integration is the trunk; main is production](https://docs.gurbanisoul.com/md/adr/0001-integration-default-branch.md): Why integration is the trunk that deploys staging and main is production, receiving only release pull requests.
- [ADR-0002: Fold heading runs into the composition, keeping the last heading's comp_id](https://docs.gurbanisoul.com/md/adr/0002-comp-id-keep-last-regroup.md): Why a run of heading lines folds into the composition it opens, keeping the last heading's comp_id and leaving permanent gaps.
- [ADR-0003: The engineering wiki lives in docs/](https://docs.gurbanisoul.com/md/adr/0003-docs-in-repo.md): Why the engineering wiki is Markdown and Mermaid under docs/, versioned with the code and reviewed in pull requests.
- [ADR-0004: One unified SemVer across web, API, and iOS](https://docs.gurbanisoul.com/md/adr/0004-unified-semver.md): Why the web, the API and the iOS app share one version number, and what that forces at release time.
- [ADR-0005: Production deploys are performed by CI after gates, not by platform git hooks](https://docs.gurbanisoul.com/md/adr/0005-ci-gated-deploys.md): Why production is deployed by CI after every required check passes, never by a platform's git hook.
- [ADR-0006: Banis are a registry of pointers over the verbatim corpus; non-SGGS text is a separate labelled layer](https://docs.gurbanisoul.com/md/adr/0006-bani-registry-over-verbatim-corpus.md): Why Nitnem banis are a registry of pointers over the verbatim corpus, with non-SGGS text kept as a separate labelled layer.
- [ADR-0007: Three repositories — data, platform, app — joined by pinned artifacts](https://docs.gurbanisoul.com/md/adr/0007-three-repositories.md): Why the project is split into data, platform and app repositories joined by pinned, checksummed artifacts.
- [ADR-0008: The platform consumes the dataset by pin, never by copy](https://docs.gurbanisoul.com/md/adr/0008-dataset-by-pin.md): Why the platform installs the scripture database from a pinned sggs-data commit and never commits a copy.
- [ADR-0009: Production is verified continuously, and logs never carry what people search](https://docs.gurbanisoul.com/md/adr/0009-production-verification.md): How production is verified continuously by a data canary and request ids, and why logs never carry what people search.
- [ADR-0010: One image per context, behind a gateway generated from the code (staging first)](https://docs.gurbanisoul.com/md/adr/0010-services-behind-a-generated-gateway.md): Why each bounded context can run as its own image behind a gateway generated from the route table.
- [ADR-0011: The API runs as Vercel functions inside the web project (staging first)](https://docs.gurbanisoul.com/md/adr/0011-api-as-functions-in-the-web-project.md): Why the API runs as Vercel functions inside the web project on staging, and how production will follow.
- [ADR-0012: The wiki is rendered as a docs site over the Markdown in docs/](https://docs.gurbanisoul.com/md/adr/0012-docs-site.md): Why the engineering wiki gets a rendered, searchable site at docs.gurbanisoul.com while every page stays PR-reviewed Markdown in docs/, and how sibling docs and diagrams are brought in.
- [ADR-0013: The wiki links out to assistants; it does not embed one](https://docs.gurbanisoul.com/md/adr/0013-outbound-assistant-links.md): Why every wiki page offers 'Ask ChatGPT' and 'Ask Claude' as plain outbound links with a guarded instruction, what that does and does not promise, and how it sits with 'never AI-invented'.
- [ADR-0002: Fold heading runs into the composition, keeping the last heading's comp_id](https://docs.gurbanisoul.com/md/data/adr/0002-comp-id-keep-last-regroup.md): ADR-0002: Fold heading runs into the composition, keeping the last heading's comp_id — documentation from Algorythmos-AI/sggs-data at the pinned commit c36e317.
- [ADR-0003: Every dataset carries its own proofs — ledger, fingerprints, quality contract](https://docs.gurbanisoul.com/md/data/adr/0003-integrity-proofs.md): ADR-0003: Every dataset carries its own proofs — ledger, fingerprints, quality contract — documentation from Algorythmos-AI/sggs-data at the pinned commit c36e317.
- [ADR-0004: The dataset is recoverable from its private backups alone, and that is drilled](https://docs.gurbanisoul.com/md/data/adr/0004-backups-and-restore.md): ADR-0004: The dataset is recoverable from its private backups alone, and that is drilled — documentation from Algorythmos-AI/sggs-data at the pinned commit c36e317.
- [ADR-0001: The app builds against pinned inputs and carries the platform's version number](https://docs.gurbanisoul.com/md/ios/adr/0001-vendored-inputs-one-number.md): ADR-0001: The app builds against pinned inputs and carries the platform's version number — documentation from Algorythmos-AI/gurbani-soul-ios at the pinned commit a386422.

## Reference

- [Glossary](https://docs.gurbanisoul.com/md/glossary.md): Definitions of the scripture, Gurmukhi and engineering terms used across the wiki — from Ang, Rahao and Vaar to comp_id, the dataset pin and golden vectors — each linkable and shown as a hover-card.
- [Repository map](https://docs.gurbanisoul.com/md/reference/repo-map.md): The three repositories — data, platform, app — and what every important path is for, one line each, as an expandable map with links into the code at the right ref.
- [Releases](https://docs.gurbanisoul.com/md/reference/releases.md): Every release of the platform as a timeline read from CHANGELOG.md — version, date, title and what kind of changes it carried — with a link to the GitHub release and a filter.
- [Diagrams and posters](https://docs.gurbanisoul.com/md/diagrams.md): The wiki's large process posters — what each one shows, how they are built from a declarative spec, the visual spec every poster must meet, and how to add one.
- [The website — gurbanisoul.com](https://docs.gurbanisoul.com/md/website.md): The public website gurbanisoul.com: DNS, SEO, Open Graph images, security headers, imagery policy, screenshots and its gates.
- [The Constellation](https://docs.gurbanisoul.com/md/website/constellation.md): How the Constellation (web and iOS) shows which themes a verse also carries: the additive caption, two rankings, encodings, lenses, the Sky and its caveats.
- [Risk Register](https://docs.gurbanisoul.com/md/risk-register.md): The project's open risks — likelihood, impact, what already mitigates each, and who owns it — reviewed at every release.
- [Reports & Audit History](https://docs.gurbanisoul.com/md/reports.md): Index of past audits, reports and plans kept for history; the live state is in the handbook.
- [The archive](https://docs.gurbanisoul.com/md/archive.md): Design notes and audit reports from the project's history, kept for the record and linked from here with the date they stopped being current — not published as pages, never a source of truth.
- [Contributing to the wiki](https://docs.gurbanisoul.com/md/contributing.md): How to write, diagram, poster and widget for this wiki so the gates pass and the pages stay true: the page rules, the diagram rules, the poster kit, the widget contract, the docs job.
- [Writing a page](https://docs.gurbanisoul.com/md/contributing/writing-docs.md): The rules a wiki page must meet: frontmatter, headings, relative links, the scripture rule, glossary terms, quizzes and code excerpts, verified stamps, and how a sibling page reaches the site.
- [Adding a diagram](https://docs.gurbanisoul.com/md/contributing/adding-a-diagram.md): Mermaid in a page: the brand palette, the accessible title and description every diagram needs, what renders on GitHub and on the site, and when a poster is the better tool.
- [Adding a poster](https://docs.gurbanisoul.com/md/contributing/adding-a-poster.md): A poster is generated from a declarative spec by the poster kit: nodes, edges, groups and steps with captions and links; the rules kit 2 enforces so it reads at the size shown; the drift check.
- [Adding a widget](https://docs.gurbanisoul.com/md/contributing/adding-a-widget.md): The contract for anything interactive on the wiki: a schema entry, a small custom element built with DOM APIs, a fallback sentence, a mocked e2e test, the budget, and how scripture may appear.
- [The docs gates](https://docs.gurbanisoul.com/md/contributing/docs-gates.md): What make docs-check and the docs job check on every pull request — frontmatter, links, widgets, the scripture rule, posters, stamps, drift, generated pages, pins, build, e2e, axe, Lighthouse.
- [Pages as Markdown, the page menu and print](https://docs.gurbanisoul.com/md/contributing/pages-as-markdown.md): Every wiki page is also published as portable Markdown, has a menu to copy, open or print it, and prints as a clean document: what each does, and what an author must keep in mind.