falltwo · falltwo · Jul 20, 2026 · Jul 20, 2026
diff --git a/.env.example b/.env.example
@@ -32,6 +32,11 @@ LINE_BRIEFING_ENABLED=false
 # Local competition/demo only. Safe default is false; never enable on a public service.
 ERP_DEMO_MODE=false
 
+# PoC tenant boundary: one SQLite database belongs to one organization.
+# Demo Mode automatically uses demo-org. Existing non-demo databases must set this,
+# then provision user_organizations and organization_entitlements before startup.
+# ERP_ORGANIZATION_ID=your-organization-id
+
 # Optional service identity for the 24-hour supply-chain news refresh.
 # The account must have risk.workspace.write; for the local demo use planner.
 ERP_SCHEDULER_ACTOR=

diff --git a/.gitignore b/.gitignore
@@ -228,3 +228,7 @@ data/erp.db-wal
 data/*preview*.db*
 .preview/
 line bot/ngrok.exe
+
+# Local AI-assistant and planning state must never enter the public repository.
+.claude/
+.planning/
diff --git a/README.en.md b/README.en.md
@@ -0,0 +1,203 @@
+# AI-Risk-Based-Inventory-ERP
+
+[繁體中文](README.md) | [English](README.en.md)
+
+[![Tests](https://github.com/falltwo/AI-Risk-Based-Inventory-ERP/actions/workflows/tests.yml/badge.svg)](https://github.com/falltwo/AI-Risk-Based-Inventory-ERP/actions/workflows/tests.yml)
+[![Release](https://img.shields.io/github/v/release/falltwo/AI-Risk-Based-Inventory-ERP?display_name=tag)](https://github.com/falltwo/AI-Risk-Based-Inventory-ERP/releases)
+![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)
+![Streamlit](https://img.shields.io/badge/UI-Streamlit-FF4B4B?logo=streamlit&logoColor=white)
+
+> **v1.0 — A governed supply-chain AI decision loop**
+> AI makes judgments and proposals; humans retain execution authority. Protected AI/Gateway procurement writes can be approved, replayed, and traced.
+
+This project is a governance-first AI Agent ERP. It connects external supply-chain risk, internal procurement data, AI recommendations, human approval, and ERP execution into one verifiable workflow—rather than stopping at a chatbot or a risk dashboard.
+
+> [!IMPORTANT]
+> v1.0 is a competition and research proof of concept. Its deployment boundary is one SQLite database per organization. It does not provide shared-database row-level multi-tenancy, external IAM/SSO, or distributed transactions, and must not be treated as a production identity or authorization service on the public internet.
+
+## v1.0 at a glance
+
+| Tier | Demo account | What it can do | What it cannot do |
+|---|---|---|---|
+| **L1 Risk Observer** | `viewer / viewer` | Risk KPIs, heatmap, alerts, read-only CSV mapping, notification preview | Cannot create proposals or modify ERP data |
+| **L2 Intelligence & Decision** | `planner / planner` | Impact analysis, What-if, alternative-supplier comparison, durable Proposal submission | Cannot approve or directly execute ERP writes |
+| **L3 Approval & Execution** | `approver / approver` | Review evidence, approve/reject, Gateway execution, audit timeline | Cannot approve its own proposal |
+
+### End-to-end decision flow
+
+```mermaid
+flowchart LR
+    NEWS["External risk intelligence"] --> L1["L1 Observe<br/>alerts, map, read-only mapping"]
+    L1 --> L2["L2 Recommend<br/>What-if, supplier alternatives"]
+    L2 --> PROP["Durable Proposal<br/>source line, price, digest"]
+    PROP --> L3["L3 Approve / Reject<br/>human decision"]
+    L3 --> GATE["Tool Gateway<br/>authorization, CAS, transaction, idempotency"]
+    GATE --> ERP["ERP Effect<br/>purchase order + receipt + audit"]
+    L3 -. "not approved" .-> STOP["zero ERP writes"]
+```
+
+## v0.1 → v1.0
+
+v1.0 preserves the governance harness completed in v0.1 and turns it into an operable supply-chain decision product.
+
+| Area | v0.1 — Governance Harness Complete | v1.0 — Governed Decision Loop |
+|---|---|---|
+| Primary outcome | Closed governance bypasses across Web, LINE, and rollback paths | Connected the governance foundation into a complete L1→L2→L3 product flow |
+| AI honesty | Code-enforced pending/denied disclosure | Separate Proposal, Approval, and Execution objects keep UI and database state aligned |
+| Supply-chain UX | Intelligence, heatmap, affected records, and recommendations existed as separate capabilities | An affected procurement line can become a governed alternative-purchase Proposal |
+| Human approval | Generic write approval with auditable state | L3 reviews source PO, supplier change, quantity, unit price, reason, and digest |
+| Execution safety | Gateway, hash-chain logs, and transaction baseline | Exact line/price identity, live revocation checks, one effect per source line, idempotent receipts |
+| Product tiers | Governance roles and capabilities | Three accounts with distinct views and least-privilege behavior |
+| Automated tests | 55 tests in the v0.1 release | **327 passing tests** in v1.0 release verification |
+| Documentation | Chinese README and architecture diagrams | Bilingual README, version comparison, honest limits, and English release notes |
+
+The v0.1 column is based on the archived release record retained by the maintainer. The private archive is intentionally not linked from public documentation.
+
+## Governance and security design
+
+- **Server-side capability checks:** role, organization membership, and entitlements are reloaded from the database; missing or revoked access fails closed.
+- **Separation of duties:** L2 proposes and L3 decides. The original proposer cannot self-approve, even after a role change.
+- **Immutable approval evidence:** a canonical payload digest covers effectful fields and binds the source PO line, supplier price row, and operation ID.
+- **Atomic execution:** protected purchase approval performs CAS state transition, ERP write, business-effect claim, execution receipt, and terminal status in one SQLite transaction.
+- **Idempotent replay:** the same operation returns its existing receipt instead of creating a second purchase order.
+- **End-to-end audit:** Proposal, approval, and execution share one operation ID; public UI surfaces expose only redacted summaries.
+- **34 governed tools:** 27 `read_only`, 1 `suggestion`, 6 `write`, and 0 `dangerous`; eight specialist Agents receive task-specific allowlists.
+
+## Architecture
+
+```mermaid
+flowchart TB
+    subgraph ENTRY["Entry and identity"]
+        WEB["Streamlit Web"]
+        LINE["LINE Bot"]
+        WEB_ACCESS["Web: Role + Membership + Entitlement"]
+        LINE_ACCESS["LINE: source allowlist + role policy"]
+    end
+
+    subgraph AI["AI orchestration"]
+        ORCH["Orchestrator Agent"]
+        AGENTS["8 specialist Agents"]
+    end
+
+    subgraph GOV["Governance"]
+        REG["Tool Registry / Allowlist"]
+        GATE["Tool Gateway"]
+        APPROVAL["Proposal / Approval / Execution"]
+    end
+
+    subgraph DATA["Data and evidence"]
+        ERP["ERP Modules"]
+        DB["SQLite"]
+        AUDIT["Audit Logs + Receipts"]
+    end
+
+    WEB --> WEB_ACCESS
+    LINE --> LINE_ACCESS
+    WEB_ACCESS --> ORCH
+    LINE_ACCESS --> ORCH
+    ORCH --> AGENTS --> REG --> GATE --> APPROVAL --> ERP --> DB
+    GATE --> AUDIT
+    APPROVAL --> AUDIT
+```
+
+The governance claims above are scoped to the protected AI/Gateway procurement workflow. Existing manual Web ERP forms have role-based access controls, but not every manual write produces a Proposal, Approval, and execution receipt.
+
+Original diagrams: [system architecture PNG](docs/images/erp_current_clean_architecture.png) · [governance flow PNG](docs/images/erp_current_standard_flowchart.png)
+
+## Quick start
+
+### 1. Install
+
+```bash
+git clone https://github.com/falltwo/AI-Risk-Based-Inventory-ERP.git
+cd AI-Risk-Based-Inventory-ERP
+
+python -m venv .venv
+# Windows
+.venv\Scripts\activate
+# macOS / Linux
+# source .venv/bin/activate
+
+pip install -r requirements.txt
+```
+
+### 2. Configure a local demo
+
+```bash
+cp .env.example .env
+```
+
+Set at least:
+
+```dotenv
+ERP_DEMO_MODE=true
+LLM_MODEL=gemini/gemini-2.5-flash
+GEMINI_API_KEY=replace_with_your_key
+```
+
+### 3. Run
+
+```bash
+streamlit run app.py
+```
+
+Known credentials such as `viewer`, `planner`, and `approver` are created and displayed only in Demo Mode. **Use this mode only on localhost; never expose it to the public internet.**
+
+## Key configuration
+
+| Environment variable | Purpose | Default / requirement |
+|---|---|---|
+| `ERP_DEMO_MODE` | Seeds synthetic data and demo users | `false`; localhost only |
+| `ERP_ORGANIZATION_ID` | Binds a SQLite database to one organization | Demo uses `demo-org`; existing non-demo databases must set it and then provision memberships and entitlements |
+| `ERP_DB_PATH` | Custom SQLite path | `data/erp.db` |
+| `LLM_MODEL` | Primary LiteLLM model | `gemini/gemini-2.5-flash` |
+| `LLM_FALLBACK_MODELS` | Comma-separated fallback models | See `.env.example` |
+| `LLM_ANALYSIS_MODEL` | Optional model for classification/translation | Primary chain when unset |
+| `GEMINI_API_KEY` / `OPENAI_API_KEY` | Provider credentials | Depends on the selected model |
+| `GNEWS_API_KEY` | Supply-chain news source | Optional |
+| `ERP_SCHEDULER_ACTOR` | Service identity for scheduled risk refresh | Disabled when unset |
+| `LINE_CHANNEL_ACCESS_TOKEN` / `LINE_CHANNEL_SECRET` | LINE Bot | Optional |
+
+## Tests and verification
+
+```bash
+pip install -r requirements-dev.txt
+python -m pytest -q
+```
+
+v1.0 local release verification: **327 passed**. CI runs on every pull request.
+
+Coverage includes:
+
+- L1/L2/L3 navigation and negative server-side authorization tests
+- Self-approval, revoked access, and cross-organization denial
+- Payload, resource-version, source-line, and price tamper rejection
+- Concurrent approval, CAS, rollback, and receipt replay
+- A single full replacement effect per source procurement line
+- Demo seed integrity with no orphan items and stable approved source-line identity across replays
+
+## Repository layout
+
+```text
+backend/                     access control, Agents, Gateway, Proposal, ERP, database
+frontend/                    Streamlit pages and L1/L2/L3 interfaces
+line bot/                    FastAPI + LINE Messaging API
+scripts/                     demo seed and operations utilities
+tests/                       governance, authorization, transaction, and UI-contract tests
+docs/                        architecture diagrams, runbooks, and release notes
+```
+
+## Known limitations
+
+- One SQLite database represents one organization; this is not shared-database row-level multi-tenancy.
+- Application audit data is tamper-evident, but a host or database administrator can still alter files directly.
+- SQLite atomicity does not automatically extend to an external ERP API; cross-system execution still needs outbox, worker, and reconciliation patterns.
+- Demo users and synthetic data must not exist in production. Production identity, membership, entitlement, and secret provisioning are deployment responsibilities.
+- Upgrading an older non-demo database without an organization boundary fails fast. Set `ERP_ORGANIZATION_ID`, then provision `user_organizations` and `organization_entitlements` before startup.
+
+## Versions
+
+- [v1.0 Releases](https://github.com/falltwo/AI-Risk-Based-Inventory-ERP/releases)
+- [v1.0 English release notes](docs/releases/v1.0.md)
+
+Stack: Python 3.11 · Streamlit · SQLite · LiteLLM · FastAPI · LINE Messaging API · Plotly