The Free I Ching

A quiet I Ching oracle with two intentional reading roles:

• Inquirer puts meaning and reflection first.
• Adept adds trigrams, line values, changing-line text, sources, and method detail.

The app also includes a searchable 64-hexagram library, a Four-Sphere-inspired reflection layer, and a journal for practices and later follow-up. See THIRD_PARTY_TEXT.md for text provenance.

Local development

The app needs no backend. Readings, questions and the journal are stored in the browser or on the device. Optional settings (Stripe link, PostHog, AdSense) are listed in .env.example.

Run:

npm install
npm run dev

Quality checks:

npm test
npm run lint
npm run build

Agent access

Assistants, crawlers and developers can read the site without scraping: prerendered HTML for every hexagram, trigram and method page, a markdown twin of each page (add .md), llms.txt, open data under /data (CC BY 4.0), and a read-only MCP server at /mcp. Build output is produced by scripts/build-agent-files.mjs. The plan and weekly review process are in docs/planning/agent-access-2026-10.md.

Optional yearly support

The web app shows a dismissible invitation after a completed reading when VITE_STRIPE_SUPPORT_URL is configured. Set it to the public URL of a Stripe Payment Link for the $10/year contribution. Card data stays on Stripe; no secret Stripe key is used by the app.

The invitation is deliberately disabled in the native iOS build. See APP_STORE_SUBMISSION.md for the App Store payment rules and release checklist.

iOS

The Capacitor project uses bundle ID com.thefreeiching.app and bundles the complete Vite build for offline use. Install dependencies, then run:

npm run native:sync
npm run native:open

native:sync builds with VITE_NATIVE_BUILD=1, which leaves PostHog analytics out of the app, and refuses to copy a bundle that still contains it (the app is declared as collecting no data). Always use it instead of npm run build && npx cap sync.

Select an Apple development team in Xcode before signing or archiving. The app icon, splash assets, privacy route, metadata, and review notes are included in the repository.

App support and privacy inquiries use [email protected] and the public support page at https://thefreeiching.com/support.

Baseline checklist

[ ] private repo + main protected + CI [x] dependabot + lockfile [ ] advisors clean (or exceptions noted) [ ] backups/PITR confirmed [x] PostHog + exceptions on [ ] uptime incl. checkout URL [ ] privacy / terms / contact (+refund/shipping/disclaimers if selling) [ ] support@ email works [ ] domain auto-renew on [ ] revenue lands in business account [ ] sales tax configured (physical goods)