JSGlobtech knowledge base

Project memory for this repository: architecture maps, integration notes, decision records, runbooks, and dated changelog drafts.

It lives inside the repo at knowledge/ and is committed to main. juned77/jsglobtech.com is private and single-owner, so committed notes are acceptable.

Never put secrets here — no API keys, tokens, webhook URLs, .env values, or customer data. Reference variable names only. Real values belong in .env.local or host secret storage.

Layout

Path	Purpose
architecture/	Stack, versions, folder layout, request/data flow
integrations/	What is actually wired: MCP, lead APIs, CRM webhook, GEO
decisions/	ADR-style records; copy 0000-template.md for new ones
operations/	Dev setup, env purposes, runbooks, production security audit, product launch / demo checklist
strategy/	Positioning, target markets, KPIs (business reasoning)
sales/	Pricing and pitch material
changelog/	Dated DRAFT entries generated per merge to main
source/	Original source documents the notes were derived from
.kb-state	Last-synced main SHA, managed by scripts/kb-sync.sh

Engineering facts live in architecture/ and integrations/; commercial reasoning lives in strategy/ and sales/. Some files there are marked commercially sensitive — do not copy them into public site copy or public/llms.txt.

Where the source playbook claims capability this repository does not implement, the derived files say so explicitly rather than repeating the claim.

Decision Record: Pricing & Proof Validated

The pricing structure was validated via MiroFish Swarm Simulation (168-round multi-agent test) and formalized in decisions/0009-pricing-and-proof-window-validation.md and decisions/0005-productized-tiers-vs-custom-scoping.md.

• Flagship Offer: Tier 2 GEO + MCP Agentic Engine ($6,000 setup + $2,000/mo retainer) anchored by a 60-day measurable AI Citation Proof Window.
• Custom Engineering: Quoted from $10k (mobile) and $5k (web) as a separate service line.
• See research/2026-10-18-mirofish-swarm-simulation-findings.md for full empirical simulation logs.

How to use it

• Reading up on the project? Start with architecture/system-overview.md (client-demo mental model), then architecture/README.md and integrations/README.md. For the commercial side, start with strategy/README.md.
• Preparing a live client demo? Start with required MVP scope sales/demo-mvp-scope.md, then master tracker operations/product-launch-checklist.md, then sales/demo-framework.md + sales/tenant-demo-checklist.md (JSGlobtech as tenant zero).
• GEO / MCP coverage gaps? See architecture/geo-mcp-gap-analysis.md (what ships vs what the playbook still claims).
• Shipping to production? Read operations/production-security-audit.md first — open Critical/High findings are blockers for multi-tenant CRM lead capture.
• Made a notable technical choice? Copy decisions/0000-template.md to decisions/NNNN-short-title.md and fill it in.
• Stack or vendor changed? Update architecture/ and/or integrations/ in the same PR as the code change.
• Work landed on main? A DRAFT changelog entry is generated for you (see below); flesh out the TODO sections with the why.

Automation

The sync script lives at scripts/kb-sync.sh in this repo. It reads knowledge/.kb-state, finds commits on main since that SHA, and writes a dated DRAFT into knowledge/changelog/.

Manual run

bash scripts/kb-sync.sh
# or
npm run kb:sync

Useful flags / env:

Flag / env	Effect
--no-commit or KB_SYNC_NO_COMMIT=1	Write files but leave them unstaged
KB_SYNC_BACKFILL=N	On first run (empty .kb-state), backfill the last N commits (default 5)

Automatic on merge

scripts/git-hooks/post-merge runs the sync after a merge, only when the current branch is main. Install it with:

bash scripts/install-git-hooks.sh

The hook never fails a merge — if the sync errors it prints a warning and exits 0.

Cursor Automation

A Cursor Automation can call the same entry point (bash scripts/kb-sync.sh). That automation is set up separately.

Safety guarantees of the sync script

• Stages and commits only the specific files it wrote under knowledge/ — never git add -A, so unrelated work in progress is never swept into a commit.
• Never pushes and never contacts a remote.
• Idempotent: re-running with nothing new prints a message and exits 0 without creating a commit or duplicate entry.
• Fails loudly (non-zero) outside a git repo or if knowledge/ is missing.

Source material

source/ holds the original documents this knowledge base was derived from — see source/README.md. Treat them as read-only inputs: when reality changes, update the derived markdown rather than the source file.