docs: product-level README, AGENTS.md split into code/reading parts, add CLAUDE.md, move task briefs to docs/tasks

- README.md is now the product/repo front door (architecture, repo map, local dev, test tiers, delivery flow, doc map). Engine positioning, VedAstro/Codex setup and the oracle/benchmark command reference move verbatim to docs/engine/README.md, docs/engine/vedastro-gateway.md and docs/benchmark/README.md. Capability badges realigned with the registry (91/78/8/0); tests/test_readme_badges.py was red on staging. - AGENTS.md: Part A (environment truth, delivery, worktrees, record placement, bug workflow, growth freeze, frontend red lines, privacy, pre-work check, test tiers) and Part B (reading-rigor constraints). GitHub issue-tracker/triage boilerplate removed: GitHub is a read-only mirror. All strings locked by tests/ are preserved. - CLAUDE.md added: roles, three working modes, task-brief sections, acceptance criteria, session discipline; imports AGENTS.md. - 50 tracked TASK-*/PROGRESS-* files and 3 never-committed briefs move to docs/tasks/ with an index; REPO_LAYOUT.md merged into README. Docs-only change (no gated path touched). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0193vBv6w5MV2cifdTUu9H5P
2026-09-03 06:56:06 +00:00
parent af411f590a
commit 8db71aaf81
63 changed files with 1958 additions and 1196 deletions
@@ -0,0 +1,322 @@
+# Jyotish 计算引擎与解读流水线（引擎层文档）
+
+> 本文从 2026-09-03 之前的根 README 拆出，描述 Python 引擎（`scripts/`、`references/`、`SKILL.md`）的定位、流水线、技法覆盖与诚实边界。产品层（网页、部署、协作流程）见根目录 `README.md`。正文保留原文，"Project Status"一节反映 v6.9.14 时期的状态，仅作历史参考。
+
+## What Is This
+
+This is a **Vedic (Jyotish) astrology analysis system** designed for deep, auditable full-chart readings. It is NOT a simple ephemeris calculator — it is a multi-stage interpretive pipeline that:
+
+1. **Computes** divisional charts (D1/D9/D10/...) via Swiss Ephemeris
+2. **Routes** 89 capability entries as a backend evidence pool (Dashas, Yogas, Shadbala, Ashtakavarga, Transits...)
+3. **Routes** the analysis through strict workflow paths depending on question type (career / relationship / wealth / timing)
+4. **Audits** every technique used — declaring what was called, what is complete/covered, and which limitations affect confidence
+5. **Degrades gracefully** — limitations are labeled, not silently over-promising
+
+### Key Differentiators (vs. PyJHora / VedAstro / Maitreya)
+
+| Feature | This Project | PyJHora | VedAstro | Maitreya |
+|---------|-------------|----------|----------|----------|
+| Full-reading pipeline (one command) | ✅ | ❌ | ❌ | ❌ |
+| Strict workflow router (per-question-type) | ✅ | ❌ | ❌ | ❌ |
+| Technique Audit Table (confidence labeling) | ✅ | ❌ | ❌ | ❌ |
+| Capability degradation (limits are explicit) | ✅ | ❌ | ❌ | ❌ |
+| MEVG external verification gates | ✅ | ❌ | ❌ | ❌ |
+| 89 capability entries routed as a backend evidence pool | ✅ | ✅ (50+) | ✅ (200+) | ✅ |
+| Traditional algorithm benchmarked | ✅ mixed depth | ✅ | ✅ | ✅ |
+| Docker / MCP Server | ✅ | ❌ | ✅ | ❌ |
+| English docs / PyPI package | ✅ in progress | ✅ | ✅ | ✅ |
+
+---
+
+### Prerequisites
+
+- Python 3.11+
+- Swiss Ephemeris (`pyswisseph` or `ephem`)
+- Optional: `pypdf`, `pdfplumber` (for PDF chart input)
+
+### Install
+
+```bash
+# Clone the repository
+git clone https://github.com/732642856/yinduzhanxing.git
+cd yinduzhanxing
+
+# Install Python dependencies
+pip install -r requirements.txt
+
+# Verify installation
+python3 scripts/audit_capabilities.py --mode validate
+# Expected: valid=true, problem_count=0
+```
+
+### Minimal Full Reading (5 minutes)
+
+```bash
+python3 scripts/jyotish_engine.py full-reading \
+  --year 1990 --month 6 --day 15 \
+  --hour 10 --minute 30 \
+  --lat 28.6139 --lon 77.2090 --tz 5.5 \
+  --age 36 \
+  --transit-date 2026-06-04
+```
+
+**Output:** ~45 computed modules, zero errors, complete structured reading with technique audit table.
+
+### Sample Output (abbreviated)
+
+```
+═══ FULL READING ═══
+Birth Data: 1990-06-15 10:30  (+5.5) 28.61°N 77.21°E
+Lagna: Gemini   Sun: Taurus   Moon: Leo
+
+── Static Analysis ──
+[✓] D1 Rashi Chart
+[✓] D9 Navamsa
+[✓] D10 Dasamsa
+[✓] Vimshottari Dasha (120 years)
+[✓] Ashtakavarga (8-point system)
+[✓] Shadbala (covered — absolute Rupa totals, component invariants verified)
+[✓] Yogas & Doshas
+[✓] Argala (planetary interventions)
+[✓] Nakshatra Advanced (Chandra Bala / Tara Bala)
+
+── Dynamic Timing ──
+[✓] Vimshottari Dasha breakdown
+[✓] Dasha Sandhi detection
+[✓] Transit (true positions)
+[✓] Double Transit analysis
+[✓] Narayana Dasha
+[✓] Solar Return / Varshaphala
+[✓] Nakshatra Dasha (Ashtottari)
+
+── Technique Audit Table ──
+✓ Vimshottari Dasha        covered      high confidence
+✓ Ashtakavarga             covered      high confidence
+✓ Shadbala                covered      absolute Rupa output; total_virupas component invariant passed
+✓ Chara Dasha             covered      KN Rao benchmark 95.83% overall match
+✓ KP Sub-Lord             covered      SubLord/SubSubLord + ABCD significator workflow
+```
+
+
+## Core Workflow
+
+### Three Input Paths
+
+| Path | Input | Behavior |
+|------|-------|----------|
+| **A: Precise birth data** | Date + time + coordinates | Full `full-reading` engine |
+| **B: PDF / text chart** | Scanned chart or description | Extract → Quality Gate → route to A |
+| **C: Uncertain birth time** | "Don't know my birth time" | Interactive birth time rectification |
+
+### Eight-Stage Pipeline
+
+```
+Stage -1: Question-type routing (career / relationship / wealth / timing)
+Stage 0:  Input routing (A / B / C)
+Stage 1:  (B only) PDF extraction + Quality Gate
+Stage 2:  Intent recognition → target house routing
+Stage 3:  Static analysis (10 steps)
+Stage 4:  Dynamic timing (7 steps)
+Stage 5:  Timing output (5-layer verification)
+Stage 6:  Remedial measures (optional)
+Stage 7:  Modern language packaging
+Stage 8:  Technique Audit Table (mandatory)
+```
+
+**Strict Workflow Router** (`references/strict-workflow-router.md`):
+- Career questions → `career-timing-strict`
+- Relationship questions → `relationship-timing-strict`
+- Wealth questions → `wealth-timing-strict`
+- Event timing → `event-timing-strict`
+- Historical verification → `event-verification-strict`
+
+The AI does NOT require the user to name techniques (e.g., "Chara Dasha"). It auto-selects based on question type.
+
+---
+
+## Technique Coverage
+
+Current registry count: **89 capability entries** (79 covered, 10 complete, 0 partial, 0 missing).
+
+These entries are a **backend evidence pool**, not a flat list of 89 user-facing
+prediction sources. Ordinary users see topic-level conclusions and evidence
+summaries. The question-domain router selects a small primary chain, then uses
+supporting indicators only to raise/lower confidence. Audit-only and alias
+entries cannot affect astrological conclusions.
+
+The table below lists representative high-value entries. Treat
+`references/technique_registry.json` as the source of truth for the full
+machine-readable registry.
+
+| Technique | Status | Notes |
+|-----------|--------|-------|
+| D1 Rashi Chart | ✅ covered | Swiss Eph base |
+| D9 Navamsa | ✅ covered | |
+| D10 Dasamsa | ✅ covered | |
+| Vimshottari Dasha | ✅ covered | |
+| Dasha Sandhi | ✅ covered | |
+| Ashtakavarga | ✅ covered | BPHS/PVR calibrated |
+| Argala | ✅ covered | |
+| Vargottama | ✅ covered | |
+| Pushkara | ✅ covered | |
+| A10 / Karma Pada | ✅ covered | |
+| UL / Upapada | ✅ covered | |
+| Transit (true positions) | ✅ covered | |
+| Double Transit | ✅ covered | |
+| Nakshatra Advanced | ✅ covered | Tara Bala / Chandra Bala / Sub-Lord workflow |
+| Narayana Dasha | ✅ covered | CLI and full-reading integration |
+| Solar Return / Varshaphala | ✅ covered | Tajika annual-chart workflow |
+| **Shadbala** | ✅ covered | **absolute Rupa component-sum output; internal invariants pass; external absolute-value oracle expansion remains open** |
+| **Chara Dasha** | ✅ covered | **KN Rao benchmark: sign 100%, duration 91.67%, overall 95.83%** |
+| KP Sub-Lord | ✅ covered | SubLord/SubSubLord + ABCD significator workflow |
+| Bhava Chalit | ✅ covered | Sripati/Porphyry/Equal/Whole Sign/Placidus/Koch |
+| Sudarshana Chakra | ✅ covered | Asc/Moon/Sun reference charts + convergence scoring |
+| Tajika Yogas | ✅ complete | Annual-chart yoga set |
+| Raj Yoga | ✅ covered | Rule-based detection |
+| Dhana Yoga | ✅ covered | Rule-based detection |
+| Pancha Mahapurusha | ✅ covered | Complete detection |
+| Neecha Bhanga | ✅ complete | Debilitation cancellation workflow |
+| Sade Sati | ✅ covered | Saturn pressure timing |
+| Tithi Lord | ✅ complete | Lunar-day ruler workflow |
+| Pancha Pakshi | ✅ complete | Five-bird system |
+| Rashi Tulya Navamsa | ✅ covered | D1/D9 mapping |
+| Trimshamsa D30 | ✅ covered | D30 varga support |
+| Marriage Counting | ✅ complete | Bhrigu Pada marriage-counting method |
+| Prashna Integration | ✅ complete | Prashna workflow integrated |
+| Bhrigu Pada Dasha | ✅ complete | Pada progression workflow |
+| Muhurta | ✅ covered | Panchanga / auspicious timing workflow |
+
+**Legend:**
+- ✅ `covered` — implemented and benchmarked against authoritative sources
+- ✅ `complete` — implemented with integrated workflow and validation hooks
+- ✅ `covered` — implemented and available in the engine, sometimes with explicit confidence caps
+- 🔶 `partial` — reserved for implemented-but-insufficiently-integrated techniques; current registry count is 0
+- ❌ `missing` — not currently present in the registry; current registry count is 0
+
+---
+
+## Why This Exists (Competitive Context)
+
+### The Landscape
+
+| Project | Type | Strength | Weakness |
+|---------|------|----------|-----------|
+| **PyJHora** | Calculation library | Strongest traditional algorithm coverage (50+ Dashas, 284 Yogas) | No interpretive pipeline; user must interpret results themselves |
+| **VedAstro** | API / Web platform | 200+ endpoints, Docker, MCP Server, MIT license | Interpretive audit & confidence labeling weaker |
+| **Maitreya** | Desktop software | Mature cross-platform GUI | Jyotish depth not as deep as specialized projects |
+| **jyotisha** | Panchanga / calendar | Excellent Panchanga accuracy | Not a full reading system |
+| **This project** | AI-native analysis system | Full pipeline + audit + degradation | Pure calculation accuracy still being benchmarked |
+
+### Our Position
+
+> **PyJHora is the calculator. VedAstro is the API platform. Maitreya is the desktop software. This project is the "AI-native Jyotish research analyst."**
+
+We are NOT trying to out-calculate PyJHora (it has years of lead). Our value is in:
+1. Organizing calculations into a **reproducible interpretive workflow**
+2. **Auditing** every technique used and declaring confidence
+3. **Degrading gracefully** — confidence caps and limitations are labeled, not silently over-promising
+4. Being **AI-native** — designed for integration with LLM-based analysis
+
+---
+
+## Honest Assessment
+
+We believe in transparency about limitations. This is NOT a "99% accurate" system, and anyone claiming that about Jyotish is over-selling.
+
+### Current Accuracy Estimates (self-evaluated)
+
+| Dimension | Score | Notes |
+|-----------|-------|-------|
+| Astronomical foundation (Swiss Eph) | 8.5/10 | Depends on ayanamsa, node mode, house system |
+| Traditional algorithm accuracy | 8.4/10 | Chara Dasha benchmark passed; Shadbala absolute Rupa invariants now pass; Dasha oracle expansion remains open |
+| Technique coverage breadth | 9.1/10 | 65 registered techniques; broad and increasingly benchmarked |
+| Reading detail depth | 9.6/10 | Possibly best among open-source projects |
+| Prediction workflow rigor | 8.8/10 | Strict routing + audit table |
+| Verification system | 8.2/10 | Has registry, benchmark, degradation; some verification still internal |
+| Engineering maturity | 7.6/10 | Docker, PyPI config and CI exist; release artifacts still need cleanup |
+| Open-source influence | 5.5/10 | Currently more of a "private high-density toolkit" |
+
+### What Confidence Caps Mean (Important)
+
+Even when a technique is labeled `covered`, it may carry a confidence or validation boundary:
+- It CAN produce output
+- Some components may still need broader external oracle expansion against PyJHora / JHora / canonical texts
+- It should be interpreted together with cross-technique evidence
+- It must NOT be the sole basis for high-confidence predictions when its limitation says so
+
+Examples:
+- `Shadbala` (covered): absolute Rupa totals are reported directly from six component sums; internal component invariants pass and `total_rupas = total_virupas / 60`, while external absolute-value oracle expansion remains open.
+- `Chara Dasha` (covered): KN Rao benchmark passes at 95.83% overall; remaining differences are documented around Aquarius/Scorpio co-lord strength arbitration.
+
+---
+
+## Project Status
+
+**Current version:** `v6.9.14`
+
+### Recently Completed
+
+- `v6.9.14` — Sudarshana Chakra complete + 475 pytest cases + 65-technique registry audit PASS.
+- `v6.9.13` — Bhava Chalit complete + transit trigger output normalization + Nakshatra test calibration.
+- `v6.9.12` — Shadbala precision upgrade + Ashtakoot 36-point compatibility + expanded subcommands.
+- `v6.9.6` — Field mapping fixes (degree→degree_in_sign + toFixed null safety); PyPI publishing config.
+- `v6.9.5` — birth_info null safety + API field mapping fixes.
+- `v6.9.4` — AI interpretation integration; current browser build disables direct model API keys and routes AI through server-side `/api/chat` or a backend proxy.
+- `v6.9.3` — 35 Dasha systems, 405+ Yoga rules, KP complete system, Prashna, 16-factor synastry, Remedies, Sahams 36, Sudarshana, PMC, Tajika.
+- `v6.1.12` — Chara Dasha KN Rao Method rewrite, PyJHora benchmark 95.83% PASS.
+- `v6.1.10` — Darakaraka deep reader wired into `full-reading.modules.jaimini.darakaraka`; thematic reports now consume real DK and Rashi Tulya Navamsa evidence.
+- `v6.1.9` — Public/sanitized benchmark suite, competitive research, coverage roadmap and PDF validation methodology added.
+- `v6.1.8` — Yoga validation reached F1=95.22% (FP=36, FN=63); thematic reports consume real `full-reading.modules` evidence.
+- `v6.1.6` — Five-system Dasha convergence wired into full-reading (Vimshottari + Chara + Yogini + Ashtottari + Kalachakra).
+- `v6.0.11` — Shadbala 1200/1200 internal invariants pass; later upgraded to absolute Rupa component-sum output.
+
+### Actively Working On (P0)
+
+1. **Release hygiene** — run the release profile, keep product-critical files tracked, rebuild wheel/sdist, and align GitHub tags with source version
+2. **README / package metadata sync** — keep public docs, registry counts and distribution artifacts consistent
+3. **Dasha oracle expansion** — add external cases for Vimshottari start/end boundaries and configurable year-length/ayanamsa comparisons
+4. **Benchmark expansion** — add more oracle cases for Shadbala, KP and annual-chart modules
+5. **Frontend verification** — keep the Next.js API contracts aligned with the Python engine output
+
+### Next (P1)
+
+- Production image publishing and smoke-test docs
+- English documentation examples and API tutorials
+- Multi-Ayanamsa UX polish and benchmark examples（计算层已可验证切换；网页设置展示和更多外部样本仍需补齐）
+
+---
+
+## Engine-level development checks
+
+### Running the Test Suite
+
+```bash
+# Syntax check all scripts
+python3 -m py_compile scripts/*.py
+
+# Capability audit (must pass with 0 problems, 0 warnings)
+python3 scripts/audit_capabilities.py --mode validate
+
+# Next.js unit tests, lint, and production build
+npm test --prefix frontend
+npm run lint --prefix frontend
+npm run build --prefix frontend
+
+# Full-reading regression test (use FICTIONAL data only)
+python3 scripts/jyotish_engine.py full-reading \
+  --year 1990 --month 6 --day 15 \
+  --hour 10 --minute 30 \
+  --lat 39.9042 --lon 116.4074 --tz 8 \
+  --age 36 \
+  --transit-date 2026-06-04
+```
+
+### Important Rules
+
+1. **NEVER** put real user birth data into skill files, tests, CHANGELOG, or public repos
+2. Use only: (a) public AA-rated celebrity data, (b) explicitly fictional smoke tests, (c) current-session data (never persisted)
+3. Always run `git status --short --branch` before starting work
+4. Always run `py_compile` + `audit_capabilities.py` + full-reading regression after modifications
+5. Do NOT remove a confidence or validation boundary without external benchmark evidence
+6. Do NOT refactor arbitrarily; make minimal verifiable changes
+
@@ -0,0 +1,201 @@
+# VedAstro Gateway、用户级入口与 Codex 插件
+
+> 本文从根 README 拆出（2026-09-03），内容原样保留：VedAstro 官方/自建/本地回退三种模式的配置、中国大陆 Gateway 部署边界、`scripts/vedastro_user_entrypoint.py` 用户级入口，以及把本仓装成 Codex 本地插件的步骤。
+
+### VedAstro：聊天产品推荐配置
+
+项目当前固定使用官方 Python SDK `vedastro==1.23.25`。首次安装依赖时必须安装到项目虚拟环境，并用同一个解释器启动后端，避免子进程落到系统 Python 后出现 `No module named vedastro`：
+
+```bash
+.venv/bin/pip install -r requirements.txt
+.venv/bin/python scripts/jyotish_api_server.py --host 127.0.0.1 --port 5200
+```
+
+在仓库根目录创建本机私有配置文件 `.env.local`。聊天场景推荐先使用下面的快速官方证据模式：
+
+```dotenv
+VEDASTRO_API_ENDPOINT=https://api.vedastro.org/api
+VEDASTRO_ENABLE_NETWORK=1
+VEDASTRO_TIMEOUT_SECONDS=20
+VEDASTRO_GATEWAY_REQUIRE_OFFICIAL_RAW_RESPONSE=1
+
+# 聊天快速模式：保留 Dasha / Chara Dasha / Shadbala / Ashtakavarga，
+# 不执行 10 行星 + 12 宫位的逐项 fan-out。
+VEDASTRO_FULL_SNAPSHOT_FANOUT_ENABLED=0
+
+# 免费公共模式下 SearchEvents 范围扫描耗时长且容易限流，
+# 聊天请求中默认关闭，避免同步阻塞流式回复。
+VEDASTRO_RANGE_SCAN_NETWORK_ENABLED=0
+
+VEDASTRO_CACHE_TTL_SECONDS=604800
+VEDASTRO_OFFICIAL_FULL_SNAPSHOT_CACHE_TTL_SECONDS=604800
+VEDASTRO_GATEWAY_QUEUE_ENABLED=1
+VEDASTRO_FREE_TIER_QUEUE=1
+VEDASTRO_FAIL_OPEN_LOCAL=1
+VEDASTRO_FULL_CATALOG_SAMPLE_LIMIT=0
+
+# 没有 key 时可先使用官方公共/免费模式；不要把 key 放到前端。
+# VEDASTRO_API_KEY=your_vedastro_key
+```
+
+该文件已被 `.gitignore` 忽略；`scripts/jyotish_api_server.py`、`scripts/vedastro_service_adapter.py`、`scripts/run_quality_gate.py` 会自动加载它。VedAstro 子进程默认复用启动后端的 `sys.executable`；如需指定独立解释器，可设置 `VEDASTRO_PYTHON_BIN=/absolute/path/to/python`。
+
+快速模式仍会取得 VedAstro 官方原始响应，并让 Gateway 在存在 `official_raw_response` 时闭合为 `official_verified`；D1/D9 等基础盘继续由本地 Swiss Ephemeris 负责。它只关闭高延迟 fan-out 与 `SearchEvents` 范围扫描，不等于关闭 VedAstro。
+
+获得稳定 API key，或把 Gateway 指向自建 VedAstro 服务后，可开启完整模式：
+
+```dotenv
+VEDASTRO_API_KEY=your_vedastro_key
+VEDASTRO_FULL_SNAPSHOT_FANOUT_ENABLED=1
+VEDASTRO_RANGE_SCAN_NETWORK_ENABLED=1
+```
+
+完整模式会增加外部请求数量和首包等待时间，更适合后台任务、预计算或非实时专业解盘，不建议直接放在聊天首轮的同步关键路径。运行 `.venv/bin/python scripts/diagnose_vedastro_mode.py` 可检查当前模式；通过 `/api/vedastro_gateway/status` 查看 Gateway 的实际配置和 readiness。
+
+AI/vibe coding 推荐入口：Cline 接本仓 MCP，Aider 负责低成本小改，Dyad 只做前端原型。运行 `python3 scripts/print_cline_mcp_config.py` 生成 Cline MCP 配置；详情见 `docs/vibe_coding_setup.md`。
+
+### 中国大陆用户：VedAstro Gateway 模式
+
+普通中国大陆用户不需要、也不应该让浏览器直连 VedAstro。推荐部署方式是：网页只访问你自己的本地或云端后端；后端通过 `VedAstro Gateway` 统一管理 self-host、official upstream、TTL/cache、free-tier queue 和 local fallback。
+
+最短配置：
+
+```bash
+cp .env.cn.example .env.local
+.venv/bin/python scripts/jyotish_api_server.py --host 127.0.0.1 --port 5200
+npm ci --prefix frontend
+npm run dev --prefix frontend
+```
+
+网页侧使用：
+
+- `Trust Center -> Web Professional Reading v1`
+- `/api/vedastro_gateway/status` 查看当前后端策略
+- `/api/vedastro_gateway/run` 生成 VedAstro-compatible evidence packet
+- `/api/professional_reading` 生成网页专业解盘包
+
+关键边界：
+
+- 不要让浏览器直连 VedAstro，也不要把 `VEDASTRO_API_KEY` 放进前端。
+- `VEDASTRO_CACHE_TTL_SECONDS` 和 `VEDASTRO_OFFICIAL_FULL_SNAPSHOT_CACHE_TTL_SECONDS` 用于缓存官方或自建服务结果。
+- `VEDASTRO_GATEWAY_QUEUE_ENABLED=1` / `VEDASTRO_FREE_TIER_QUEUE=1` 用于把昂贵或被限流的外部请求排队。
+- 如果 VedAstro 官方或自建服务不可达，`VEDASTRO_FAIL_OPEN_LOCAL=1` 会保持本地 Jyotish 引擎继续输出，并在 Technique Audit Table 里降级标注。
+- Gateway 不会默认声称跑完 641 项；它只把 capability catalog、dynamic selection、cache/queue/fallback 状态作为证据边界交给 strict workflow。
+
+### Codex 用户级 VedAstro + strict workflow 入口
+
+如果用户在 Codex 窗口从云端 Git 仓库拉取本项目，推荐先走这一条稳定入口，而不是手动拼多个底层脚本：
+
+```bash
+python3 scripts/vedastro_user_entrypoint.py \
+  --year YYYY --month MM --day DD --hour HH --minute mm \
+  --lat LAT --lon LON --tz TZ \
+  --question "事业机会什么时候出现" \
+  --themes career,marriage,wealth \
+  --reference-date 2026-07-02 \
+  --format markdown
+```
+
+机器读取或交给后续 agent 处理时使用 JSON：
+
+```bash
+python3 scripts/vedastro_user_entrypoint.py \
+  --year YYYY --month MM --day DD --hour HH --minute mm \
+  --lat LAT --lon LON --tz TZ \
+  --question "事业机会什么时候出现" \
+  --themes career,health,education,property,children,migration,prashna \
+  --reference-date 2026-07-02 \
+  --format json
+```
+
+这个入口会自动做四件事：
+
+1. 读取 `.env.local` 并诊断当前是 `official_extended` 还是 `fast_local_fallback`。
+2. 启动 `official_full_capability_catalog`，给 VedAstro 官方能力目录生成 `domain / execution_policy / adjudicator_use / confidence_role / blocked_reason`。
+3. 按 `--themes` 做动态选择，避免把健康、教育、房产、子女、迁移、Prashna 等非三大主题塞进 `general`。
+4. 触发 strict workflow 合同摘要，输出 primary route、可用 route、cache/TTL/free-tier queue 策略和 honesty boundary。
+
+边界必须保留：这个入口**不会把 641 项全部当作已执行**。它先做官方能力目录分类和主题选择；能自动执行的进入证据层，需要第二人资料、用户文本、校时画像或官方网络预算的方法会保持 `needs_user_context`、`needs_user_text`、`needs_rectification_profile` 或 `blocked`。
+
+#### 作为 Codex 本地插件安装
+
+本仓现在带了最小插件包装：`.codex-plugin/plugin.json`。它复用现有 `skills/` 与根目录 `mcp_server.py`，适合你把当前仓直接装进 Codex 本机环境。
+
+1. 先把本仓登记到个人 marketplace：
+
+```bash
+python3 <home>/.codex/skills/.system/plugin-creator/scripts/create_basic_plugin.py \
+  jyotish-vedic-astrology \
+  --path ~/.codex/plugins \
+  --marketplace-path ~/.agents/plugins/marketplace.json \
+  --marketplace-name personal \
+  --with-marketplace
+```
+
+上面是 Codex 官方脚本的标准 marketplace 流。如果你要让 **当前仓本身** 被安装，关键不是用 scaffold 目录跑能力，而是让 `~/.agents/plugins/marketplace.json` 里的 `jyotish-vedic-astrology` 条目最终指向当前仓路径。
+
+最少要确认这一条存在：
+
+```json
+{
+  "name": "jyotish-vedic-astrology",
+  "source": {
+    "source": "local",
+    "path": "<repo>"
+  }
+}
+```
+
+2. 若本机还没把 personal marketplace 接进 Codex：
+
+```bash
+codex plugin marketplace add ~/.agents/plugins/marketplace.json
+```
+
+3. 安装插件：
+
+```bash
+codex plugin add jyotish-vedic-astrology@personal
+```
+
+4. 检查是否已被识别：
+
+```bash
+codex plugin list
+```
+
+5. 开一个**新线程**再测试。Codex 只会在新线程里重新拾取新装的 skills / MCP。
+
+#### 本地更新 / 重装
+
+当你改了 `.codex-plugin/plugin.json`、`skills/` 或 `mcp_server.py`：
+
+```bash
+python3 <home>/.codex/skills/.system/plugin-creator/scripts/update_plugin_cachebuster.py \
+  <repo>
+
+codex plugin add jyotish-vedic-astrology@personal
+```
+
+然后重新开新线程验证。
+
+推荐的 official extended `.env.local` 示例：
+
+```bash
+VEDASTRO_API_ENDPOINT=https://api.vedastro.org/api
+VEDASTRO_ENABLE_NETWORK=1
+VEDASTRO_TIMEOUT_SECONDS=20
+VEDASTRO_CACHE_TTL_SECONDS=600
+VEDASTRO_OFFICIAL_FULL_SNAPSHOT_CACHE_TTL_SECONDS=600
+VEDASTRO_FREE_TIER_QUEUE=1
+# 可选
+# VEDASTRO_API_KEY=sk_live_xxx
+```
+
+先运行：
+
+```bash
+python3 scripts/diagnose_vedastro_mode.py
+```
+
+若仍显示 `fast_local_fallback`，用户级入口仍可运行，但解盘必须把 VedAstro official 证据写成 blocked/降级，不能声称 official extended 已闭环。