Productize jyotish app release surface

docs/research/desktop_packaging_spike_2026_06_23.md

@@ -0,0 +1,86 @@
+# Desktop Packaging Spike — Jyotish App
+
+Date: 2026-06-23
+
+## Decision
+
+Use a staged desktop path:
+
+1. **Now: PWA install** for the current Vite app. This is already live through `manifest.webmanifest`, `sw.js`, and the Trust Center install state.
+2. **Short term: Pake shell** for a lightweight Mac/Windows/Linux desktop wrapper when the user can run both local services:
+   - Vite/static app served from `jyotish-app/dist` or `npm run preview`.
+   - Python API served by `scripts/jyotish_api_server.py` on `127.0.0.1:5200`.
+3. **Later: Tauri shell with sidecar** when the app needs a one-click bundle that starts the Python API automatically and ships stricter desktop permissions.
+
+This avoids prematurely adding Rust/Tauri scaffolding before the local API sidecar and signing strategy are fixed.
+
+## Product Requirements
+
+- Desktop shell must keep the current local-first data model: browser storage, local Python API, no cloud dependency for chart calculation.
+- API calls must stay local-only by default: `127.0.0.1:5200` or explicit user override.
+- Packaging must preserve installability signals: app name, icon, theme color, standalone display, cached shell, and Trust Center notes.
+- PDF/HTML/JSON export and local case libraries must work in the shell.
+- Offline behavior can cache the UI shell, but Python-backed calculations still require the local API process.
+
+## Pake Path
+
+Use when speed matters and the user accepts running the API separately.
+
+Candidate flow:
+
+```bash
+cd jyotish-app
+npm run build
+npm run preview -- --host 127.0.0.1 --port 4173
+python3 ../scripts/jyotish_api_server.py --host 127.0.0.1 --port 5200
+```
+
+Then package the local web URL with Pake using the project icon/name. The exact Pake command should be pinned only after verifying the installed Pake CLI version, because CLI flags can change.
+
+Risk: Pake wraps a URL. It does not solve local API lifecycle, signing/notarization, or multi-process supervision by itself.
+
+## Tauri Path
+
+Use when the app needs a true desktop artifact.
+
+Tauri is the better long-term fit because it uses the system webview, has a security-focused Rust base, supports arbitrary frontends, and can model desktop permissions. It can later run the Python API as a sidecar or replace it with a Rust/native command layer.
+
+Candidate architecture:
+
+- `src-tauri/tauri.conf.json` points `frontendDist` to `../dist` and `devUrl` to Vite.
+- A sidecar starts `python3 scripts/jyotish_api_server.py --host 127.0.0.1 --port 5200`.
+- Frontend still talks to `http://127.0.0.1:5200/api/...`.
+- Permissions initially allow only app shell, local file download/export, and loopback HTTP.
+
+Risk: Requires Rust toolchain, platform signing decisions, API sidecar packaging, and explicit lifecycle handling. Do not add scaffolding until these are tested on the target OS.
+
+## Preflight Checklist
+
+Run:
+
+```bash
+python3 scripts/desktop_packaging_preflight.py
+python3 tests/run_frontend_click_smoke.py --mode all
+```
+
+Expected output:
+
+- Vite package has `build` and `preview`.
+- Manifest has name, standalone display, scope, start URL, theme color, and icon.
+- Service worker caches shell files and excludes `/api/`.
+- HTML links the manifest and icon.
+- API server binds to `127.0.0.1` by default.
+- Trust Center exposes install/local-first status.
+- Browser click smoke reports `offline_recovery_guidance_visible: true` when the API is absent.
+
+## 安装后首次打开
+
+普通用户路径必须先验证“壳能打开”，再验证“本地 API 可诊断”：
+
+1. **PWA installed shell**：运行 `python3 tests/run_frontend_click_smoke.py --mode all`。预期结果包含 `manifest.webmanifest`、`serviceWorker: true`、移动首屏检查、在线核心流程和离线恢复提示。
+2. **Pake first launch**：先 `cd jyotish-app && npm run build && npm run preview -- --host 127.0.0.1 --port 4173`，再启动 `python3 ../scripts/jyotish_api_server.py --host 127.0.0.1 --port 5200`。Pake 只包装 URL，不负责 Python API 生命周期。
+3. **Tauri sidecar readiness**：在真正生成 `src-tauri` 前先跑 `python3 scripts/desktop_packaging_preflight.py`，确认 loopback API、manifest、service worker、Trust Center、离线恢复都仍可检查。若 `offline_recovery_guidance_visible` 不为 true，不应进入 Tauri sidecar 打包。
+
+## Next Build Step
+
+After this spike, the next practical step is a Pake smoke artifact only if the machine has Pake installed. If not, keep PWA as the release path and move to the ephemeris abstraction spike.

docs/research/ephemeris_abstraction_feasibility_2026_06_23.md

@@ -0,0 +1,34 @@
+# Ephemeris Abstraction Feasibility - 2026-06-23
+
+Purpose: make the ephemeris roadmap probeable instead of relying on UI labels or memory from prior windows.
+
+## candidate_backends
+
+| Backend | Current role | replacement_readiness | license_posture | Decision |
+|---|---|---|---|---|
+| `swisseph_python` | Primary local Python API path through `scripts/jyotish_api_server.py` | `primary` | Current Swiss Ephemeris boundary must stay explicit in settings, exports, and docs | Keep as canonical longitude source |
+| `swisseph_wasm` | Browser/local-first degradation path through bundled WASM assets and `@swisseph/browser` / `swisseph-wasm` dependencies | `fallback` | Same Swiss Ephemeris boundary as the Python path | Keep as fallback, not a separate accuracy oracle |
+| `xalen_ephemeris` | External Apache-2.0 Rust candidate from `vedika-io/xalen-ephemeris` | `spike_only` | Favorable for experiments, but no local adapter or parity matrix exists yet | Do not expose as real runtime replacement until a parity spike passes |
+| `vedastro` | MIT full-stack product/API benchmark | `product_api_benchmark` | Can inform API, OpenAPI, chat, Panchanga, and product workflow design; C# core should stay behind an API/service boundary if reused | Reuse product/API ideas, not as a drop-in Python ephemeris |
+| `pyjhora_benchmark` | Broad JHora-style behavior/oracle benchmark | `benchmark_only` | AGPL; do not copy implementation code into this app unless the whole downstream license posture is changed | Use only expected outputs, public examples, and behavior comparisons |
+
+## Probe
+
+Run:
+
+```bash
+python3 scripts/ephemeris_backend_probe.py
+```
+
+The probe returns JSON with `candidate_backends`, `license_posture`, and `replacement_readiness`. It is intentionally read-only and network-free, so it can be used in regression checks without mutating user data or depending on GitHub availability.
+
+## Engineering Decision
+
+The app already records `ephemerisBackend` in calculation settings and export provenance. That is useful, but it is not enough to claim backend replacement. The real next step is an adapter contract:
+
+- input: UTC datetime, latitude, longitude, ayanamsa policy, node policy, body list
+- output: tropical longitude, sidereal longitude, speed, retrograde flag, ayanamsa value, backend metadata
+- parity gate: compare Moon, Sun, Ascendant, Rahu/Ketu, and daily boundary cases against `swisseph_python`
+- acceptance: document max deltas before any new backend can be selectable as a runtime calculation source
+
+Until that exists, `swisseph_python` remains the production source, `swisseph_wasm` remains the fallback, `xalen_ephemeris` remains a spike candidate, `vedastro` remains a product/API benchmark, and `pyjhora_benchmark` remains an AGPL behavior benchmark only.

docs/research/ephemeris_adapter_contract_2026_06_23.md

@@ -0,0 +1,50 @@
+# Ephemeris Adapter Contract - 2026-06-23
+
+Purpose: define the real engineering gate before `xalen_ephemeris`, `vedastro`, or any other `candidate_backend` can become a selectable runtime ephemeris source.
+
+## Contract
+
+The executable contract lives in:
+
+```bash
+python3 scripts/ephemeris_adapter_contract.py
+```
+
+It defines `EphemerisAdapterContract`, `PARITY_CASES`, and JSON output fields that every backend must satisfy:
+
+- input fields: UTC-adjusted birth date/time, latitude, longitude, timezone, `ayanamsa_policy`, `node_policy`, and `body_list`
+- output fields: sidereal longitude, sign, degree in sign, speed, `retrograde`, nakshatra metadata when available, `ayanamsa_value`, backend name, and source metadata
+- baseline: `swisseph_python`
+- candidate slot: `candidate_backend`
+
+## acceptance_thresholds
+
+The first parity gate is `sun_moon_asc_nodes`:
+
+| Body | Max `longitude_delta_arcsec` |
+|---|---:|
+| Sun | 1.0 |
+| Moon | 1.0 |
+| Ascendant | 5.0 |
+| Rahu | 2.0 |
+| Ketu | 2.0 |
+
+These thresholds are strict enough to catch accidental tropical/sidereal, timezone, node, and ayanamsa mismatches, while leaving a small practical tolerance for backend representation differences.
+
+## Parity Matrix
+
+Current `PARITY_CASES`:
+
+| Case | Why it exists |
+|---|---|
+| `beijing_first_use_demo` | Reuses the first-use demo chart so product smoke and ephemeris smoke share a reference |
+| `delhi_lagna_boundary` | Guards Ascendant, Lahiri ayanamsa, timezone, and mean-node behavior in an India-centered case |
+| `new_york_moon_boundary` | Guards western timezone conversion and Moon/nakshatra boundary behavior |
+
+Current decision:
+
+- `swisseph_python` remains the production baseline.
+- `swisseph_wasm` remains the browser fallback and can later be compared through the same matrix.
+- `xalen_ephemeris` remains `spike_only` until a local adapter can produce this exact contract.
+- `vedastro` remains a product/API benchmark unless used behind a service boundary that emits this contract.
+- `pyjhora_benchmark` remains AGPL benchmark-only and should provide oracle expected values, not copied implementation code.

docs/research/ephemeris_candidate_adapter_spike_2026_06_23.md

@@ -0,0 +1,40 @@
+# Ephemeris Candidate Adapter Spike - 2026-06-23
+
+Purpose: decide whether a non-default `candidate_backend` is ready to enter the `EphemerisAdapterContract` parity gate.
+
+Run:
+
+```bash
+python3 scripts/ephemeris_candidate_adapter_spike.py
+```
+
+## swisseph_wasm_candidate
+
+`swisseph_wasm_candidate` has local browser assets and package dependencies, so it is a plausible offline/PWA candidate. It is not a separate accuracy authority and it is not ready for `runtime_setting_exposure`.
+
+The `license_gate` is the important blocker: Swiss Ephemeris WASM still follows Swiss Ephemeris licensing boundaries, so distribution claims must be reviewed before this becomes a user-selectable backend.
+
+The local package metadata currently reports:
+
+| Package | `package_license` |
+|---|---|
+| `@swisseph/browser` | `AGPL-3.0` |
+| `swisseph-wasm` | `GPL-3.0-or-later` |
+
+That means the WASM path is useful for local/PWA fallback experiments, but it must not be treated as a low-risk proprietary desktop dependency without a license decision.
+
+## xalen_ephemeris_candidate
+
+`xalen_ephemeris_candidate` remains the best permissive-direction spike because `vedika-io/xalen-ephemeris` is tracked as Apache-2.0. There is no local executable mirror in this workspace yet, so the current spike status is documentation-only.
+
+## Gate
+
+Both candidates are blocked until `parity_gate_required` is satisfied:
+
+1. Produce rows matching `EphemerisAdapterContract`.
+2. Compare against `swisseph_python` baseline rows.
+3. Pass `longitude_delta_arcsec` thresholds for Sun, Moon, Ascendant, Rahu, and Ketu.
+4. Preserve `ayanamsa_value`, `retrograde`, backend metadata, node policy, and house policy.
+5. Keep `runtime_setting_exposure` blocked until the above is verified.
+
+Decision: do not expose any non-SwissEph runtime setting yet. The next implementation step is an isolated executable adapter only after local assets and license review are complete.

docs/research/open_source_scan_2026_06_22.md

@@ -0,0 +1,55 @@
+# Open Source Jyotish Scan — 2026-06-22
+
+Purpose: keep the product audit grounded in current open-source projects instead of relying only on older comparison notes.
+
+## Live GitHub Checks
+
+The live GitHub API scan on 2026-06-22 confirmed these current reference points:
+
+| Project | Current signal | License signal | Reuse posture | Product lesson |
+|---|---:|---|---|---|
+| VedAstro/VedAstro | ~568 stars, active full-stack C#/web/API project | MIT | Direct for API/product ideas; C# code not copied into Python path | Product completeness: website, API, OpenAPI-style surface, AI/chat experience |
+| CNWU16/vedic-astro-skills | ~338 stars, fast-growing skill toolkit | MIT | Direct for skill/report workflow ideas already mirrored under `references/open_source_sources/vedic-astro-skills` | Methodology depth: report rules, house framework, P1-P12 audit, reader/rectifier flows |
+| naturalstupid/PyJHora | ~190 stars, AGPL | Caution: benchmark and behavioral reference, not copy-paste into permissive code | Breadth benchmark: JHora-style dasha, varga, yoga, AV, Tajika, GUI/test corpus |
+| adarshj322/dashaflow | Low-star but focused Python package; query matched Shadbala/Ashtakavarga/Muhurta | MIT | Direct; local mirrored code exists under `references/open_source_sources/dashaflow` | Practical reusable kernels for Muhurta, AV, Shadbala, Jaimini, matching, career |
+| northtara/jyotishganit | Local mirror available | MIT | Direct for modern Python data-layer comparisons | Deterministic component separation: varga, panchanga, strengths, AV, JSON-LD |
+| diliprk/VedicAstro | Local mirror available | MIT/research noted | Direct for adapted KP sublord logic | KP-specific RL/NL/SL/SSL and horary workflow |
+| RoxyAPI/jyotish-vedic-astrology-app | 2026 Next.js template with Kundli, Panchang, Ashtakoot Gun Milan, Vimshottari Dasha, dosha analysis | MIT | Product benchmark; depends on external RoxyAPI rather than local copy | Treat matching as a guided first-class workflow |
+| RoxyAPI/vedic-astrology-starter-app | 2026 React Native/Expo starter with Gun Milan, Manglik, Navamsa, Panchang, Sade Sati | MIT | Mobile/product benchmark | Saved profiles and mobile matching flow matter |
+| emmetCode/nakshatra | 2026 JS Ashtakoot/Nadi-focused project | No license detected | Benchmark only | Kuta/Nadi factors need explanatory UI, not just a score |
+| Akshay-S-PY/RashAi | Vite/vanilla JS Vedic app with kundali, matching, panchang, muhurta, AI insights | No license detected | Product benchmark | Lightweight apps still surface matching as a primary module |
+| VedAstro/Vedic-Astrology-AI-MCP-Server | MCP/AI wrapper with compatibility matching topic | No license detected in search result | API/agent benchmark | Compatibility should be callable from agent/API surfaces |
+
+## Local Mirror Status
+
+`scripts/audit_fragments.py` currently detects seven local source mirrors:
+
+- `references/open_source_sources/VedicAstro`
+- `references/open_source_sources/dashaflow`
+- `references/open_source_sources/jaimini-tropical`
+- `references/open_source_sources/jyotishganit`
+- `references/open_source_sources/panchanga_api`
+- `references/open_source_sources/rishi-ai-mcp`
+- `references/open_source_sources/vedic-astro-skills`
+
+## Immediate Product Rules
+
+1. Prefer MIT/Apache local source mirrors for direct code reuse.
+2. Treat AGPL/GPL projects such as PyJHora as behavioral benchmarks unless the whole downstream license posture is explicitly accepted.
+3. Any registry technique marked `covered` or `complete` must have at least one real CLI/API/script surface and at least one real output path.
+4. UI productization is not just a tab: it must expose readable conclusions, evidence, next action, mobile-safe layout, and hidden raw JSON for audit.
+5. Matching/synastry productization is not just Moon-degree input: it must support saved partner selection, full birth-data calculation, explanatory Kuta/Nadi factors, D9/Kuja/Dasha context, and exportable pair records.
+
+## New Guardrail
+
+`python3 scripts/audit_fragments.py --strict` now cross-checks:
+
+- `references/technique_registry.json`
+- `scripts/jyotish_engine.py` CLI commands
+- `scripts/jyotish_api_server.py` API routes
+- `jyotish-app/` frontend API markers
+- `tests/` references
+- local open-source mirrors
+- untracked workspace residue and `.git/lost-found` fragments
+
+This is the repeatable check for the “different windows left scattered fragments” concern.

docs/research/product_gap_matrix_2026_06_22.md

@@ -0,0 +1,114 @@
+# Jyotish Product Gap Matrix — 2026-06-22
+
+Purpose: keep the web/app roadmap tied to same-category product expectations, live open-source scans, and local fragment audits. The registry audit can be 65/65 while product parity is still incomplete.
+
+## Evidence Baseline
+
+| Source | Signal | Product lesson | Reuse posture |
+|---|---|---|---|
+| `scripts/audit_fragments.py --strict` | 65 registry techniques, 37 CLI commands, 35 API endpoints, 42 frontend files, 0 hard gaps | Capability registry is covered; product gaps must be tracked separately | Local guardrail |
+| `references/open_source_sources/vedic-astro-skills` | MIT skill/report/rectifier toolkit mirrored locally | Report workflow, P1-P12 audit, rectifier flow, validation rules | Direct for workflow and report packaging |
+| `references/open_source_sources/dashaflow` | MIT Python kernels mirrored locally | Panchanga, Muhurta, Shadbala, Ashtakavarga, matching, career kernels | Direct where architecture fits |
+| `references/open_source_sources/jyotishganit` | MIT Python component model mirrored locally | Separate deterministic components, JSON-LD style output, Panchanga objects | Direct for data-contract ideas |
+| `references/open_source_sources/jaimini-tropical` | Local web app with Panchanga cards and export | Product UX pattern for Panchanga and plain-text export | Direct after license review |
+| `VedAstro/VedAstro` GitHub scan | 568 stars, MIT, API/web/OpenAPI/chat/Panchanga topics | Full-stack product surface matters as much as calculation breadth | Direct for product/API ideas, not direct C# copy |
+| `vedika-io/xalen-ephemeris` GitHub scan | 879 stars, Apache-2.0, Rust ephemeris, active in 2026 | Ephemeris abstraction and settings provenance should be a first-class long-term track | Candidate benchmark/integration spike |
+| `naturalstupid/PyJHora` GitHub scan | Broad JHora-style feature reference, AGPL | Breadth benchmark and validation fixture source | Benchmark only unless license posture changes |
+| `dineshpaudel/acharavidya` GitHub scan | MIT, Python/PyPI Panchanga calculations including Muhurta and Rahu Kala | Panchanga product parity includes inauspicious day parts, not just Tithi/Nakshatra | Candidate direct reference after source review |
+| `jayeshmepani/panchang-core` GitHub scan | MIT, Panchang/Muhurta/raw JSON export product surface | Calendar APIs need exportable structured rows and event windows | Product/API benchmark; PHP code not copied |
+| `RoxyAPI/jyotish-vedic-astrology-app` GitHub scan | MIT Next.js app with Panchang, Ashtakoot Gun Milan, Vimshottari Dasha, dosha analysis | Same-category apps expose Gun Milan as a guided product flow | Product/API benchmark; external API dependency not copied |
+| `emmetCode/nakshatra` GitHub scan | JS Ashtakoot/Nadi-focused app, no license detected | Matching UX should explain Kuta/Nadi factors, not only return a total score | Benchmark only unless license becomes clear |
+| `Akshay-S-PY/RashAi` GitHub scan | Vite/vanilla JS Vedic app with kundali, matching, panchang, muhurta, AI insights | Lightweight web apps still make matching a first-class module | Product benchmark |
+| `VedAstro/Vedic-Astrology-AI-MCP-Server` GitHub scan | AI/MCP wrapper with compatibility matching topic | Agent/API surfaces should expose compatibility as callable workflow | Product/API benchmark |
+
+## P0 Product Parity Gaps
+
+| Gap | Current state | Same-category expectation | Next implementation task | Done when |
+|---|---|---|---|---|
+| Calculation settings and provenance center | 参数/日历面板 now shows engine, ayanamsa, ephemeris, house/node strategy, chart style, saved-chart status, and export provenance | User can inspect and later change calculation settings; exports preserve assumptions | Add setting selectors for ayanamsa/node/house/sunrise/geocoder policies | User can see the calculation basis before trusting a reading |
+| Panchanga calendar product | Birth-time Panchanga + Tithi Lord are visible; `/api/panchanga_range` returns date ranges, month grid, activity filtering, Rahu Kala/Yamaganda/Gulika, day/night Choghadiya, planetary Hora windows, SwissEph `rise_trans` sunrise/sunset, SwissEph Tithi/Nakshatra/Yoga end times, richer tithi/nakshatra/vara vrata tags, masa-dependent festival candidates, condition tags, all/any combined condition search, `search_summary`, `festival_details`, location-aware summary, CSV and ICS export | Daily/weekly/monthly Panchanga cards, Rahu Kala/Yamaganda/Gulika, calendar export, end times, vrata/festival rules, day/night sub-windows | Add masa-aware festival naming and dedicated festival drill-down pages | User can use the app as an almanac, not only a natal chart |
+| Saved chart workspace | Main UI now reuses `jyotish_chart_library`: save current chart, open selected chart, delete with confirmation, export selected chart, show local library status, use time-aware chart IDs with legacy ID compatibility, export case libraries, unified chart/pair/prashna case list, group/relation/tag metadata, and group/relation filters | Chart library, case workspace, profile compare, share/export workflow | Add editable metadata and profile compare shortcuts | User can return to charts without opening chat |
+| Professional report pipeline | Export JSON/SVG/PNG exists; HTML report export produces a standalone printable artifact; `/api/report_artifact` generates backend HTML/PDF artifacts through `report_builder.py`; `/api/thematic_report` now derives real chart/dasha/yoga/shadbala/AV/relationship/career/Jaimini evidence when birth/chart payload is present | Printable HTML/PDF report with evidence, settings, boundaries, and narrative | Add method docs/cURL/OpenAPI snippets and fold thematic sections into final report artifact UX | One-click HTML/PDF and thematic reports work with evidence provenance and safe fallbacks |
+| Product-grade chart workspace | South/North Indian charts exist | North/South/East styles, varga grid, print layout, comparison chart | Stabilize chart style controls and add varga grid/report print states | Professional user recognizes the app as chart software |
+
+## P1 Deep Parity Gaps
+
+| Gap | Current state | Same-category expectation | Next implementation task |
+|---|---|---|---|
+| Calculation catalog/API explorer | `/api/technique_catalog` now exposes searchable registry/productization/UX/API metadata, `api_docs`, row-level `method_docs`, cURL snippets, and minimal OpenAPI operations; `/api/technique_example` runs whitelisted sample payloads; Skill workbench directory cards can run examples with current chart payloads and displays thematic evidence source | Searchable calculation catalog, method docs, API examples | Continue polishing method explanations and expose copy affordances in UI |
+| Rectification scanner UX | Rectification panel exists | Event list, time scan candidates, heatmap, reasoned winner | Reuse `vedic-astro-skills/.../time_scan.py` concepts and local rectifier |
+| Rule explorer and variant toggles | Settings/export chain records rule variants; `/api/yogas`, `/api/ashtakavarga`, `/api/shadbala` now return result-level `rule_variants`; Skill workbench renders Yoga/Shadbala rule evidence | Yoga/KP/Jaimini/AV variants visible and switchable | Extend realtime variant metadata to KP/Jaimini result cards and add copyable method docs |
+| Benchmark dashboard | Tests and benchmark reports exist | Per-module precision table against JHora/PyJHora/VedAstro-style references | Build static benchmark summary from `benchmarks/jyotish/reports` |
+| Relationship/family workspace | Synastry has manual birth-data flow, quick Moon longitude flow, deep D9/Kuja/Dasha context, relationship report templates, bi-wheel/composite-style comparison view, spouse-status yoga evidence, UL/DK relationship timing evidence, print-polished relationship HTML/PDF report export, saved partner selection, saved pair records, pair reopen/delete controls, editable chart/pair/prashna case metadata, current-pair JSON/HTML/PDF export, and pair records now carry partner/group metadata in the unified case workspace | Saved partners, bi-wheel/composite-like comparison, dasha sync, relationship case records | Continue with Panchanga search/details and calculation-settings selectors |
+
+## P2 Platform Gaps
+
+| Gap | Current state | Same-category expectation | Next implementation task |
+|---|---|---|---|
+| Offline/PWA/desktop packaging | Vite app now has manifest, SVG icon, service worker shell cache, install prompt handling, PWA status, desktop packaging spike, and `scripts/desktop_packaging_preflight.py` | Installable PWA or Pake/Tauri-style desktop shell | Run Pake smoke only when CLI is available; defer Tauri until Python sidecar/signing strategy |
+| Privacy and trust center | Trust Center now explains local-first storage, local API boundary, AI/remote boundary, local record counts, export local data, terminology preference, and confirm-clear local data | Clear data location, API-key handling, deletion/export controls | Add deeper account/API-key documentation after desktop path |
+| First-use onboarding and empty-state path | First screen now offers API health check, demo birth fill, import focus, and actionable saved-library empty copy | New users can create or inspect a chart without reading docs first | Browser smoke the first-run path on mobile and desktop after the next full build |
+| Localization modes | Chinese/English labels plus入门/专业/梵文优先 terminology mode | Beginner/pro terminology switch, glossary depth, Sanskrit spellings | Continue copy QA as features expand |
+| Ephemeris abstraction | SwissEph/WASM + Python API, calculation provenance records `ephemerisBackend`; backend probe, adapter contract, and candidate spike now report readiness, `package_license`, runtime exposure gates, `PARITY_CASES`, `sun_moon_asc_nodes`, and `longitude_delta_arcsec` thresholds | Replaceable ephemeris backend and explicit accuracy notes | Add a real executable candidate adapter only after local assets/license review are complete |
+
+## Fragment Triage Queue
+
+These files are not hard failures, but they must be classified before the product can be called fully audited:
+
+| Fragment | Likely value | Triage decision needed |
+|---|---|---|
+| `reading_orchestrator.py` | Full-reading workflow | Referenced by `/api/thematic_report.workflow_orchestration`; keep as workflow vocabulary and future registry execution layer |
+| `report_orchestrator.py` | Report packaging | Reused by `/api/thematic_report`; now supports sample, custom, and derived real-evidence modes |
+| `report_builder.py` | Report generation | Reused by `/api/report_artifact` for backend HTML/PDF artifact generation; keep for future thematic report assembly |
+| `tithi_analyzer.py` | Panchanga depth | Merged into `/api/chart` as `tithi_lord_analysis`; surfaced in 参数/日历 and HTML report |
+| `shadbala_advanced.py` | Strength calibration | Integrated into `/api/shadbala.advanced_layer`; keep as evidence layer, not total-score override |
+| `dasha_analyzer.py` | Dasha narrative | Integrated into `/api/dasha.vimshottari_analysis` and Dasha UI cards |
+| `spouse_status_yoga.py` | Relationship depth | Fold into relationship workspace |
+| `curse_yoga_detector.py` | Yoga special cases | Integrated into `/api/yogas.curse_yogas` and Skill workbench boundary cards |
+| `hermes_bridge.py` | Agent bridge | External personal WorkBuddy/Hermes automation; archived outside product surface because it writes `~/.workbuddy` |
+| `orchestrator_bridge.py` | Agent bridge | Referenced by `/api/thematic_report.workflow_orchestration` as report pipeline bridge |
+| `mevg_automation.py` | Validation automation | Integrated as read-only `/api/case_validation.mevg_gate` protocol/status source |
+
+## Immediate Execution Order
+
+1. Completed: visible provenance/Panchanga/workspace panel in the main web app.
+2. Completed: static tests guard the panel, Tithi Lord, HTML report export, and Panchanga starter entry.
+3. Completed: JSON export metadata carries provenance; HTML report exports a readable artifact.
+4. Completed MVP: `tithi_analyzer.py` and `/api/muhurta` are wired into product flow; `report_builder.py` is triaged as PDF backend pattern.
+5. Completed MVP: Panchanga starter upgraded to `/api/panchanga_range`, Rahu Kala/Yamaganda/Gulika rows, and CSV export.
+6. Completed MVP: Panchanga range now uses chart location for sunrise/sunset when available and supports ICS export.
+7. Completed MVP: Panchanga month grid, activity filters, and SwissEph `rise_trans` sunrise/sunset precision are wired into API and web panel.
+8. Completed MVP: Tithi/Nakshatra/Yoga end times and Ekadashi/Pradosham/Purnima/Amavasya tags are wired into API, month grid, table, CSV, and ICS export.
+9. Completed MVP: Choghadiya and planetary Hora sub-day windows are wired into API, month grid, table, CSV, and ICS export.
+10. Completed MVP: dedicated saved chart workspace reuses `jyotish_chart_library` with save/open/delete/export in the main UI.
+11. Completed MVP: Synastry can select a saved partner chart from the local library and reuse the full Ashtakoot + D9 + Kuja + Dasha comparison path.
+12. Completed MVP: Synastry pair records now save to `jyotish_synastry_pair_library`, show recent saved pairs, and export the current comparison JSON.
+13. Completed data fix: saved chart IDs now include birth time and still recognize legacy IDs, preventing same-day/same-place charts from overwriting each other.
+14. Completed MVP: pair reopen/delete controls and current synastry HTML report export are wired into the saved case workflow.
+15. Completed MVP: richer Panchanga vrata/festival-candidate rules and search-by-condition are wired into API, month grid, table, CSV, ICS and tests.
+16. Completed MVP: unified chart/pair/prashna case workspace now has group/relation/tag metadata, group/relation filters, chart rows in case search, selected chart export/delete, and open-chart actions.
+17. Completed MVP: relationship report templates now summarize Ashtakoot/D9/Kuja/Dasha evidence, persist with saved pair records, replay from old/new case data, and export into HTML reports.
+18. Completed MVP: bi-wheel/composite-style comparison view now shows relationship axes, planet overlay houses, sign relationship tone, and Sun/Moon/Venus/Mars midpoints in the full synastry flow.
+19. Completed MVP: `spouse_status_yoga.py` is folded into `/api/relationship`, full synastry deep context, relationship report evidence, saved pair replay/export, and HTML report output.
+20. Completed MVP: relationship HTML report export now has a print-polished deliverable section with conclusion hero, evidence cards, bi-wheel axes, overlay table, midpoint cards, spouse-status cards, action lists, and boundaries.
+21. Completed MVP: unified case workspace now edits chart/pair/prashna label, group, relation, and tags in place, preserving existing JSON import/export shape.
+22. Completed MVP: backend report artifact/PDF pipeline now exposes `/api/report_artifact`, reuses `report_builder.py`, blocks active HTML, returns `pdf_base64` or HTML fallback, and is wired to the web export menu.
+23. Completed MVP: richer relationship timing/UL-DK fold-in now returns `/api/relationship.relationship_timing`, reuses `darakaraka_reader.py` and `jaimini.py`, renders UL/DK+Dasha trigger cards in full synastry, and exports `uldk-print-grid` in HTML/PDF reports.
+24. Completed MVP: Panchanga search enhancement now supports all/any condition combinations, festival explanation cards, backend `search_summary`/`festival_details`, and location-aware calendar summaries.
+25. Completed MVP: calculation settings selectors now persist ayanamsa/node/house/sunrise/geocoder policy, attach settings to chart payload/provenance, and preserve assumptions in JSON/HTML/PDF export paths.
+26. Completed MVP: calculation catalog/API Explorer now exposes `/api/technique_catalog`, whitelisted `/api/technique_example`, endpoint/action mapping, current-chart sample payloads, and searchable/runnable Skill workbench cards.
+27. Completed MVP: Yoga/Shadbala rule fragments now run through product APIs: `/api/yogas` reuses `curse_yoga_detector.py` and `/api/shadbala` reuses `shadbala_advanced.py`; Skill workbench renders both with rule boundaries.
+28. Completed MVP: `dasha_analyzer.py` now powers Vimshottari analysis inside `/api/dasha`, while `dasha_calculator_enhanced.py` supplies five-level Dasha context for UI cards.
+29. Completed MVP: remaining workflow/bridge fragments are classified: thematic report exposes reading/report/orchestrator bridge metadata, case validation exposes MEVG gate status, Hermes bridge is archived as external personal automation rather than product UI.
+30. Completed MVP: `/api/thematic_report` now upgrades from sample evidence to `derived_chart_evidence` when birth/chart payload is provided, and the UI exposes evidence source/module status.
+31. Completed MVP: Technique Directory/API Explorer now exposes method docs, cURL snippets, minimal OpenAPI operations, endpoint notes, and row-level API doc keys.
+32. Completed MVP: PWA manifest/service worker/installability status and local-first Trust Center are visible in the app.
+33. Completed MVP: terminology mode now affects glossary display and provenance/JSON/HTML export.
+34. Completed spike: desktop packaging path is documented, README links it, and `scripts/desktop_packaging_preflight.py` checks PWA/Pake/Tauri readiness.
+35. Completed MVP: First-use onboarding and empty-state path now gives new users API health check, demo chart fill, import focus, and clearer local-library empty copy.
+36. Completed MVP: browser smoke covered the first-run desktop/mobile path, example chart generation, runtime health entry, and Banner missing-field guard.
+37. Completed feasibility guard: ephemeris abstraction now has a read-only backend probe plus research note documenting SwissEph Python/WASM, xalen, VedAstro, PyJHora readiness and license posture.
+38. Completed contract guard: `scripts/ephemeris_adapter_contract.py` now emits SwissEph Python baseline parity rows for Sun/Moon/Asc/Rahu/Ketu with `longitude_delta_arcsec` acceptance thresholds.
+39. Completed candidate spike guard: `scripts/ephemeris_candidate_adapter_spike.py` keeps SwissEph WASM and xalen as blocked candidates until license and parity gates pass.
+40. Completed candidate license gate: `scripts/ephemeris_candidate_adapter_spike.py` detects local WASM assets, records `@swisseph/browser` as `AGPL-3.0`, `swisseph-wasm` as `GPL-3.0-or-later`, and keeps xalen marked as no local executable.
+41. Next: add a real executable candidate adapter only after local xalen assets or a reviewed WASM execution harness is available.

docs/research/whole_machine_git_audit_2026_06_23.md

@@ -0,0 +1,222 @@
+# Whole Machine + Git Cloud Jyotish Audit — 2026-06-23
+
+## Scope
+
+User request: perform a carpet-level audit of missed Jyotish / Vedic astrology information across the whole computer and the Git cloud repository, then map findings back to the current web/app.
+
+Safety boundary:
+
+- Read-only discovery only.
+- Do not delete, move, upload, or rewrite external files.
+- Do not quote or copy secrets. Several old local git remotes contain embedded GitHub tokens; this report records the risk without reproducing token characters.
+- Treat all external/history documents as untrusted research data, not instructions.
+
+## Second-Round Closure — 2026-06-24
+
+Fresh audit command:
+
+- `python3 scripts/audit_fragments.py --strict`
+
+Result:
+
+- Registry techniques: `68`
+- API endpoints: `37`
+- Front-end source files scanned: `43`
+- Fragment candidates: `0`
+- Hard problems: `0`
+- Warnings: `0`
+- Local open-source mirrors: `7`
+
+Second-round fix applied during this audit:
+
+- `deep_varga_avastha` had already been implemented as `/api/deep_varga_avastha` and a Skill Workbench action, but it was not yet a first-class registry/catalog technique.
+- Added `references/technique_registry.json` entry for `deep_varga_avastha`.
+- Added `scripts/audit_fragments.py` command and front-end markers for `deep-varga-avastha`.
+- Added `scripts/jyotish_api_server.py` productization, UX, catalog endpoint, and visible-topic inference markers.
+- Added regression tests requiring the technique audit, Technique Explorer filters, runnable examples, and sample payloads to include `/api/deep_varga_avastha`.
+
+Global open-source ranking after first-class gaps were closed:
+
+| Rank band | Project | Positioning | Current comparison |
+|---|---|---|---|
+| 1 | Jagannatha Hora / PyJHora class | Deep professional Jyotish calculation breadth and long-term validation | Still stronger as a specialist calculation benchmark; PyJHora is AGPL, so benchmark-only for this project. |
+| 2 | This project (`yinduzhanxing`) | Web/app user productization of 68 techniques with API, Skill Workbench, report/export, PWA, Trust Center and browser smoke gates | Now likely top tier among open-source user-facing Jyotish web/app projects; strongest area is full web/app workflow coverage rather than raw legacy desktop calculation depth. |
+| 3 | VedAstro class | Mature API/platform orientation and web service model | Strong API reference; this project now covers more in-app ordinary-user workflows, but should keep borrowing platform/API discipline. |
+| 4 | VedicAstro / panchanga API / RoxyAPI templates | Focused API or starter-app coverage | Useful references for KP, panchanga and app scaffolding; current project is broader and more productized. |
+| 5 | Single-purpose libraries | Panchanga, dasha, ephemeris or MCP fragments | Useful as specialized references, not comparable as full ordinary-user apps. |
+
+Current conclusion:
+
+- The previous first-class productization gap list is closed at registry/API/front-end/catalog level: Ashtakavarga PAV/Yoga Pinda, Sripathi/Placidus switch, KP Horary, Tajika Harsha/Panchavargiya Bala, Muhurta date-range solver, and Sayanadi/Shayanadi + D24/D30/D60 templates are now implemented and guarded.
+- Remaining competitive gap is no longer "missing obvious skill capability"; it is release hardening: cloud sync/branch hygiene, full browser/release quality gate, external benchmark fixtures, and production packaging.
+- The largest current project risk is workspace hygiene: many important product files are still untracked locally, so cloud deploys or ordinary-user builds from GitHub may miss them until the work is staged/committed.
+
+## Git Cloud Evidence
+
+Primary remote in current repo:
+
+- `origin`: `git@github.com:732642856/yinduzhanxing.git`
+- current branch: `codex/release-hygiene-ci`
+
+Cloud access attempts:
+
+- SSH `git ls-remote` failed because port 22 timed out.
+- HTTPS `git ls-remote https://github.com/732642856/yinduzhanxing.git` succeeded.
+- GitHub REST API anonymous request was rate-limited.
+- HTTPS mirror clone succeeded into `/tmp/yinduzhanxing-mirror.git`, then checked out into `/tmp/yinduzhanxing-cloud`.
+
+Cloud refs found:
+
+- `refs/heads/main` -> `4ff624812c7b9ec762a801f7219f9c2f5079e907`
+- `refs/heads/codex/release-hygiene-ci` -> `11bdee3ba1f480aff38440ad58cfbb81bfa5567d`
+- tags: `v6.0.47`, `v6.0.48`, `v6.0.49`, `v6.0.50`, `v6.0.51`, `v6.0.52`
+
+Cloud checkout facts:
+
+- `/tmp/yinduzhanxing-cloud` checked out `codex/release-hygiene-ci`.
+- Cloud HEAD: `11bdee3ba1f480aff38440ad58cfbb81bfa5567d`
+- Cloud tree: `d3a89944bb1c319120f61f66a88c879d0fa28375`
+- Cloud file count excluding `.git`: `720`
+- Cloud text/code-like file count: `654`
+
+Local workspace facts:
+
+- Local file count excluding `.git`: `1525`
+- Local text/code-like file count: `938`
+- Local contains many build/cache/runtime outputs not present in cloud: `.pytest_cache`, `.ruff_cache`, `build/`, `dist/`, `jyotish-app/dist/`, `jyotish-app/node_modules/`, `__pycache__`, generated benchmark outputs.
+- Tracked local diff is much larger than the cloud branch diff and includes active productization work in app/API/tests/docs.
+
+Cloud branch diff against `origin/main`:
+
+- 17 files changed.
+- 192 insertions, 125 deletions.
+- Mostly release hygiene, CI, README/SKILL docs, packaging manifest, quality gate, and small API/build fixes.
+
+## Whole-Machine High-Value Sources
+
+High-signal local sources found outside the current project:
+
+- `/Users/wuyongnaren/.workbuddy/skills/jyotish-vedic-astrology`
+- `/Users/wuyongnaren/Projects/星轨资料恢复/17-Skills技能库/jyotish-vedic-astrology`
+- `/Users/wuyongnaren/Projects/星轨资料恢复/25-相关Skills补充/jyotish-vedic-astrology`
+- `/Users/wuyongnaren/engines-repo/jyotish`
+- `/Users/wuyongnaren/Documents/星轨talk/engines-repo/jyotish`
+- `/Users/wuyongnaren/WorkBuddy/engines-repo/jyotish`
+- `/Users/wuyongnaren/WorkBuddy/2026-06-09-20-03-34/jyotish-fragments`
+- `/Users/wuyongnaren/WorkBuddy/2026-06-10-21-30-47`
+- `/Users/wuyongnaren/WorkBuddy/2026-06-12-15-22-12`
+- `/Users/wuyongnaren/.workbuddy/brain`
+- `/Users/wuyongnaren/文件仓库/印度占星文章`
+- `/Users/wuyongnaren/文件仓库/中外🔮占星/国外占星/印度占星书`
+
+Important historical reports found:
+
+- `印度占星Skill_真实Bug与遗漏清单_v6.1.11.md`
+- `Yinduzhanxing_开源对标与优化报告_v6.1.11.md`
+- `开源印度占星项目搜索报告.md`
+- `vedic-astrology-open-source-research.md`
+- `印度占星Skill全面审计与能力评估报告-v3.0.md`
+- `jyotish_improvement_plan.md`
+- `jyotish_capability_assessment.md`
+
+## Open Source Sources Already Present Locally
+
+Current project already contains local mirrors under `references/open_source_sources`:
+
+- `jyotishganit`
+- `jaimini-tropical`
+- `VedicAstro`
+- `rishi-ai-mcp`
+- `dashaflow`
+- `panchanga_api`
+- `vedic-astro-skills`
+
+Historical reports repeatedly classify reuse posture as:
+
+- MIT / suitable for direct reuse or adaptation: `VedicAstro`, `dashaflow`, `vedic-astro-skills`, parts of `jyotishganit`, `happyalu/panchang-muhurt` where license permits.
+- AGPL/GPL / benchmark or independent rewrite only: `PyJHora`, `vedic-calc`, some SwissEph WASM packages.
+
+## Historical Missing-Feature Consensus
+
+The recurring non-UI gaps from older reports:
+
+- Ashtakavarga Prashtara / PAV source contribution table
+- Ashtakavarga Kakshya
+- Yoga Pinda
+- Bhava Bala
+- Navatara / Tara Bala
+- Kantaka Shani
+- Pushkara Navamsa / Pushkara Bhaga
+- Ishta / Kashta Phala
+- Sripathi / Placidus house systems
+- 36 Sahams
+- Tajika strength layers: Harsha Bala, Panchavargiya Bala
+- KP Horary
+- Deeper Prashna: Sphuta / Trisphuta / Prana-Deha-Mrityu
+- Muhurta solver
+- Vimshottari multiple start points
+- Sayanadi / Shayanadi Avastha
+- D24 / D30 / D60 deeper interpretive templates
+
+## Current Coverage Matrix
+
+Legend:
+
+- `covered`: registry/API/engine or front-end has a meaningful implementation path.
+- `partial`: some backend or docs exist, but the product/API/user flow is incomplete.
+- `reference-only`: only docs or open-source reference exists; no first-class product implementation.
+
+| Area | Current Status | Evidence | Gap |
+|---|---:|---|---|
+| Navatara / Tara Bala | partial | `scripts/nakshatra_advanced.py`, `tests/test_nakshatra.py`, registry has Nakshatra Advanced | Tara Bala exists, but Navatara itself is not first-class in skill-map/product cards. |
+| Kantaka Shani | covered | `scripts/sade_sati.py`, `/api/sade_sati`, registry note | User-facing depth may still be limited to the Sade Sati surface. |
+| Pushkara | covered | `scripts/jyotish_engine.py`, `jyotish-app/main.js`, registry | Covered in D9/marriage and full-reading contexts. |
+| Ishta / Kashta Phala | partial | Shadbala references and tests mention Ishta/Kashta | No standalone registry/API/front-end module. |
+| Ashtakavarga Prashtara | reference-only | `references/open_source_sources/dashaflow/ashtakavarga.py`, old reports | Current `scripts/ashtakavarga.py` has BAV/SAV; Prashtara source contribution table not productized. |
+| Yoga Pinda | reference-only | `references/feature-gap-matrix-2026.md` | No engine/API/front-end implementation found. |
+| Kakshya | covered | `scripts/kakshya.py`, `/api/kakshya`, `computeKakshya`, tests | Covered as backend/API; check if product surface is prominent enough. |
+| Bhava Bala | covered | `scripts/bhava_bala.py`, `/api/bhava_bala`, skill-map card | Covered as backend/API and app card. |
+| Sripathi / Placidus | partial | `scripts/bhava_chalit.py`, API example uses `house_system: sripati`; VedicAstro has Placidus references | Setting exists around Bhava Chalit, but not a clear user-facing house-system selector/parity gate. |
+| 36 Sahams | covered | `scripts/tajika.py`, `scripts/varshaphala.py`, `/api/annual`, `/api/prashna` | Covered in annual/prashna contexts. |
+| Harsha / Panchavargiya Bala | reference-only | roadmap and feature matrix | No first-class engine/API/front-end implementation found. |
+| KP Horary | partial | `references/open_source_sources/VedicAstro/vedicastro/horary_chart.py`, `scripts/prashna.py` has simplified KP Prashna | MIT source exists but VedicAstro horary is not directly integrated as a product module. |
+| Prashna Sphuta / Trisphuta | covered | `scripts/prashna.py`, tests assert `trisphuta`, front-end renders Sphuta points | Covered. |
+| Muhurta solver | partial | `scripts/muhurta.py`, `/api/muhurta`, tests | Scoring exists; full constraint solver/date-range search is still unclear. |
+| Vimshottari multiple start points | partial | `scripts/extended_dashas.py`, `nakshatra_dasha.py`, registry Dasha variants | No clear setting for all traditional 12 Vimshottari start points. |
+| Sayanadi / Shayanadi Avastha | partial | `scripts/avastha_calculator.py` includes Shayanadi | Registry does not expose Sayanadi/Shayanadi as a separate capability; front-end status is partial. |
+| D24 / D30 / D60 deep reading | partial | `scripts/divisional_charts_extended.py`, `trimshamsa_d30.py`, tests | Calculations exist; deep interpretive templates for D24/D30/D60 remain thinner than D1/D9/D10. |
+
+## Highest Priority Remaining Gaps
+
+1. Ashtakavarga Prashtara + Yoga Pinda
+   - Why: Professional Ashtakavarga tools need source contribution tables, not only BAV/SAV totals.
+   - Reuse: `dashaflow/ashtakavarga.py` can be studied/adapted if license allows; current local `scripts/ashtakavarga.py` already has calibrated BAV/SAV.
+
+2. Sripathi / Placidus house-system productization
+   - Why: Settings mention house systems, but the user-facing app still needs a trustworthy switch, provenance, and parity warning.
+   - Reuse: VedicAstro horary/houses references and current `bhava_chalit.py`.
+
+3. KP Horary via VedicAstro
+   - Why: Historical reports rank VedicAstro as the best MIT source for KP Horary.
+   - Reuse: `references/open_source_sources/VedicAstro/vedicastro/horary_chart.py`.
+
+4. Harsha / Panchavargiya Bala for Tajika
+   - Why: Annual Varshaphala already exists, but Tajika strength judgement is incomplete without these layers.
+   - Reuse: historical notes and reference docs; avoid AGPL copying.
+
+5. Muhurta constraint/date-range solver
+   - Why: Current Muhurta scoring is not the same as a usable search workflow.
+   - Reuse: `dashaflow/muhurtha.py`, `panchanga_api`, `happyalu/panchang-muhurt` if license permits.
+
+6. Sayanadi/Shayanadi Avastha + D24/D30/D60 deep templates
+   - Why: These are expert-depth gaps, not first-minute UX gaps.
+   - Reuse: current `avastha_calculator.py`, `divisional_charts_extended.py`, and existing reference templates.
+
+## Next Action
+
+Start with Ashtakavarga Prashtara + Yoga Pinda because it is:
+
+- Repeated across historical reports.
+- Still not present in registry/API/frontend as a first-class capability.
+- Close to existing calibrated Ashtakavarga code, so implementation risk is bounded.
+- Highly visible for professional users comparing this app against real Jyotish tools.