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)
