Build TermKit Studio and TermSpec 0.2 foundation

.github/workflows/ci.yml

@@ -27,11 +27,23 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.11"
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.3.14"
       - run: uv sync --all-extras --locked
+      - run: bun install --frozen-lockfile
+        working-directory: apps/studio
       - run: uv run ruff check .
       - run: uv run mypy src
       - run: uv run python scripts/export_schemas.py --check
       - run: uv run pytest --cov --cov-report=xml
+      - run: bun run check
+        working-directory: apps/studio
+      - run: bun run test
+        working-directory: apps/studio
+      - run: bun run build
+        working-directory: apps/studio
+      - run: uv run python scripts/embed_studio_assets.py --check
       - run: uv build
       - name: Rehearse example pack
         run: |

.gitignore

@@ -19,3 +19,8 @@ site/
 *.db
 *.sqlite*
 .termkit/
+.obsidian/
+apps/studio/node_modules/
+apps/studio/dist/
+apps/studio/*.tsbuildinfo
+*.termdb

CHANGELOG.md

@@ -7,12 +7,30 @@ versions are tracked independently.
 
 ### Added
 
-- Established the concept-first TermSpec 0.1 foundation.
-- Added deterministic TermPack source loading, cross-record validation,
-  license gating, reproducible archive building, and safe verification.
-- Added provider-neutral resolution, longest-match selection, explicit
-  ambiguity warnings, TermPlan output, and terminology checking.
-- Added Forge, Registry, exchange, provider, domain, and sense-resolution ports.
-- Added lazy entry-point discovery with third-party loading disabled by default.
-- Added CLI, optional HTTP adapter, offline tests, CI, schemas, example pack,
-  architecture decisions, governance, security, and contribution guidance.
+- Added TermSpec 0.2 domain schemes, external identifiers, concept-first
+  candidates, ChangeSets, review decisions, revisions, source revisions and corpora.
+- Added an Alembic-backed local workspace with canonical indexing, draft
+  isolation, optimistic conflicts, separate language/domain review, atomic
+  deterministic writes, history and compensating undo.
+- Added TermKit Studio, a dense local-first React/Vite workbench with Concepts,
+  Candidates, Review, Sources, Relations, Exchange, Runtime and Releases.
+- Added CSV and XLSX mapping, TBX and SKOS normalization, identity
+  reconciliation, conflict previews and atomic import ChangeSet generation.
+- Added an OpenRefine Reconciliation API v0.2 adapter for external concept
+  matching without canonical writes.
+- Added dependency-closed runtime compilation, exact locks, a separate SQLite
+  FTS5 index, serialized Aho–Corasick scanning and offline benchmark metrics.
+- Added concept-first Forge batches and separated persistent candidates from
+  bounded, reproducible Forge run metadata.
+- Added Studio/API/CLI documentation, security guidance, CI frontend gates and
+  embedded wheel assets, plus the independent original-data `TermKit-Packs`
+  repository scaffold.
+
+### Changed
+
+- Upgraded the software pre-release to `0.2.0a0` and canonical Studio writes to
+  TermSpec 0.2 while retaining a documented TermSpec 0.1 read path.
+- Deprecated pair-shaped `CandidateTerm` as a compatibility input; Forge now
+  emits concept, lexical, relation and alignment records.
+- Source summaries now derive revision, corpus segment, candidate and referenced
+  concept counts from normalized workspace identity instead of naming patterns.

README.md

@@ -2,103 +2,227 @@
 
 # TermKit
 
-**Concept-first infrastructure for professional multilingual terminology.**
+**Concept-first infrastructure and a local-first workbench for professional terminology.**
 
-Build, validate, version, install, resolve, and audit domain terminology packs
-without coupling terminology data to one translation provider.
+Curate evidence, review semantic changes, build immutable terminology packs,
+and compile deterministic runtime indexes—without tying your data to one model
+or translation provider.
 
-[简体中文](README.zh-CN.md) · [Architecture](docs/architecture.md) ·
-[TermPack format](docs/termpack-format.md) · [Plugin system](docs/plugin-system.md)
+[简体中文](README.zh-CN.md) · [Studio architecture](TERM_KIT_STUDIO_ARCHITECTURE.md) ·
+[TermSpec](docs/termspec.md) · [TermPack format](docs/termpack-format.md)
+
+[![CI](https://github.com/ZilaiWang/TermKit/actions/workflows/ci.yml/badge.svg)](https://github.com/ZilaiWang/TermKit/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![TermSpec 0.2](https://img.shields.io/badge/TermSpec-0.2-315C43)](docs/termspec.md)
+[![License: MIT](https://img.shields.io/badge/License-MIT-2F2F2F.svg)](LICENSE)
 
 </div>
 
 > [!IMPORTANT]
-> TermKit is a working project name and the repository is at a pre-alpha
-> foundation stage. Public contracts are intentionally small; compatibility is
-> not guaranteed until the first stable TermSpec release.
+> TermKit is pre-alpha. TermSpec 0.2 and the local Studio are implemented as the
+> long-term architecture, but public compatibility is not guaranteed until 1.0.
+
+![TermKit Studio concept workspace](.github/screenshots/studio-concepts.jpg)
+
+TermKit Studio keeps concept identity, multilingual lexical entries, evidence,
+relations and revision state visible in one dense workspace. Canonical files do
+not change until an explicit ChangeSet passes validation and is applied.
 
 ## What TermKit is
 
-TermKit is infrastructure for a future ecosystem of professional language
-resources. Its model is concept-first: a hydraulic pump is one concept with
-definitions, relations, multilingual lexical entries, evidence, review state,
-and provenance—not a collection of unrelated bilingual string pairs.
+TermKit treats a termbase as governed knowledge rather than a table of bilingual
+word pairs. One language-neutral concept owns definitions, domain membership,
+relations, provenance and lifecycle state; each language-specific name is a
+separate lexical entry with its own status, policy, sense and evidence.
+
+```text
+Concept → Evidence → Curation → Review → Package → Runtime
+```
+
+The repository contains three product surfaces:
+
+- **TermKit Core** — TermSpec 0.2, deterministic TermPack tooling, Forge
+  contracts, Exchange planning, dependency locks, and provider-neutral runtime.
+- **TermKit Studio** — the official local-first React/FastAPI workbench for
+  concepts, candidates, review, sources, relations, exchange, runtime and releases.
+- **TermRegistry** — immutable package discovery and verified local installation;
+  a hosted registry is deliberately not required.
 
-The first repository contains four logical components:
+Studio is not a SaaS dashboard. It opens a terminology repository on your own
+machine. YAML and JSONL remain canonical; the workspace SQLite database is a
+derived editing/index layer, and every semantic edit is an auditable ChangeSet.
 
-- **TermSpec** defines concepts, lexical entries, evidence, sources, quality,
-  manifests, dependencies, and lock files.
-- **TermRuntime** performs normalized longest-match discovery and produces
-  provider-neutral `TermPlan` decisions for translation and validation.
-- **TermForge** defines an auditable candidate-production and review pipeline;
-  extraction and alignment algorithms are plugins.
-- **TermRegistry** defines immutable package discovery and installation ports;
-  the first implementation is a verified local installer.
+## Highlights
 
-Terminology data belongs in separate repositories. Every pack declares its own
-license, sources, maintainers, and redistribution policy.
+- **Concept-first modeling** — represent one meaning once, then attach any
+  number of BCP 47 language entries, definitions, relations and evidence.
+- **Governed curation** — draft semantic operations, review language and domain
+  decisions independently, and keep rationale plus revision history.
+- **Standards-aware exchange** — map CSV/XLSX, normalize TBX and SKOS, preview
+  identity conflicts, and expose OpenRefine Reconciliation API v0.2.
+- **Deterministic runtime** — resolve dependencies, write an exact lock, compile
+  FTS5 plus an Aho–Corasick matcher, and explain every terminology decision.
+- **Local by default** — canonical data stays Git-friendly and Studio binds to
+  loopback; no hosted account or proprietary database is required.
 
 ## Quick start
 
+From a source checkout, requirements are Python 3.11+,
+[uv](https://docs.astral.sh/uv/), Bun 1.3+, and Git:
+
 ```bash
 uv sync --all-extras
+cd apps/studio && bun install --frozen-lockfile && bun run build && cd ../..
+uv run termkit studio examples/packs/demo-hydraulics
+```
+
+Studio opens at `http://127.0.0.1:8765/studio`. It binds to loopback by default;
+non-loopback hosting requires an explicit override because Studio has no hosted
+authentication boundary. Release wheels embed the production Studio build, so
+installed users only need `termkit[studio]`; Bun is a contributor dependency.
+
+Core workflows remain available without the UI:
+
+```bash
 uv run termkit validate examples/packs/demo-hydraulics
 uv run termkit pack build examples/packs/demo-hydraulics --output dist/
+uv run termkit runtime compile \
+  --pack examples/packs/demo-hydraulics \
+  --output dist/demo-hydraulics.termdb \
+  --lock-output dist/termkit.lock
 uv run termkit resolve \
   "The boom cylinder is controlled by the pilot valve." \
   --pack examples/packs/demo-hydraulics \
   --source-language en \
   --target-language zh-Hans
 ```
 
-## Repository map
+## Studio workflow
+
+| Workspace | Purpose |
+| --- | --- |
+| Concepts | Faceted, virtualized concept and multilingual lexical editing |
+| Candidates | Context-first reconciliation of Forge output into concepts |
+| Review | PR-style semantic diffs with separate language/domain decisions |
+| Sources | Provenance, authority, content identity and rights inspection |
+| Relations | Hierarchy-first browsing plus governed relation ChangeSets |
+| Exchange | CSV/XLSX mapping wizard and normalized TBX/SKOS import planning |
+| Runtime | Explainable resolve/check plus independent `.termdb` compilation |
+| Releases | Validation gates and deterministic build/verification |
+
+`⌘K` / `Ctrl+K` opens the command palette. The interface is intentionally dense,
+quiet and keyboard-friendly; machine assistance belongs behind Forge and
+reconciliation capabilities, not at the center of the product.
+
+### Review semantic changes
+
+![TermKit Studio review workspace](.github/screenshots/studio-review.jpg)
+
+A draft is an ordered semantic diff rather than an opaque form submission.
+Language and domain reviewers decide separately, provide rationale, and approve
+the same ChangeSet before canonical source is updated.
+
+### Explain runtime decisions
+
+![TermKit Studio runtime lab](.github/screenshots/studio-runtime.jpg)
+
+Runtime Lab shows source offsets, concept identity, selected pack, target term,
+policy and evidence. The same bounded result can be consumed through the Python
+API, local HTTP API or a compiled `.termdb` index.
+
+### Validate and build immutable releases
+
+![TermKit Studio release workspace](.github/screenshots/studio-releases.jpg)
+
+Release gates validate schema, references, languages, evidence and rights before
+building a deterministic `.termpack`; the produced archive is verified in the
+same workflow and reported with its SHA-256 digest.
+
+## Curation lifecycle
+
+```text
+source revision → corpus → Forge candidates → reconciliation
+       → ChangeSet → language/domain review → canonical source
+       → TermPack + lock → compiled runtime index
+```
+
+Machine or plugin output never becomes approved terminology directly. It first
+produces candidates with occurrence context and quality signals; a curator then
+matches an existing concept, creates a concept, attaches a lexical entry,
+defers, merges or rejects the proposal. See [Studio](docs/studio.md),
+[Exchange](docs/exchange.md) and [Runtime](docs/runtime.md) for the complete
+workflows.
+
+## Architecture
 
 ```text
-src/termkit/
-  spec/       Stable concept, lexical, evidence, and manifest contracts
-  pack/       Safe, deterministic TermPack build/load/verify operations
-  runtime/    Matching, resolution, term plans, and translation checking
-  plugins/    Entry-point discovery, descriptors, and typed plugin protocols
-  forge/      Candidate pipeline and review workflow ports
-  registry/   Package registry and installer ports
-  server/     Optional HTTP adapter
-  cli.py      Thin command-line adapter
-examples/     Original, redistributable demonstration packs
-tests/        Offline contract, boundary, pack, runtime, and plugin tests
-docs/         Architecture, governance, security, format, and ADRs
+canonical YAML + JSONL
+        │ open / hash / index
+        ▼
+workspace.sqlite ── draft ChangeSet ── review ── validated atomic write
+        │                                           │
+        │ candidate/review/history                   ▼
+        └──────────────────────────────────── canonical source
+                                                    │
+                         build TermPack / resolve dependencies / lock
+                                                    ▼
+                      immutable .termpack       derived .termdb
+                                                FTS5 + matcher
 ```
 
-Dependency direction is enforced in tests: `spec` is the center, while CLI,
-server, providers, storage, and third-party algorithms stay at the edges.
+The two SQLite files have different ownership and lifecycles:
+
+- `.termkit/workspace.sqlite` contains local editing state, candidates, review
+  decisions and derived canonical indexes;
+- `.termkit/runtime/*.termdb` contains only resolved pack data, FTS5 search and
+  a serialized deterministic Aho–Corasick matcher.
+
+See [architecture.md](docs/architecture.md) and the accepted
+[Studio architecture](TERM_KIT_STUDIO_ARCHITECTURE.md) for invariants.
 
-## Standards strategy
+## Repository map
 
-TermKit does not replace terminology standards. The internal JSONL format is
-optimized for Git review, streaming, and reproducible builds. Conversion
-adapters will target TBX-Basic first, then SKOS where concept graphs benefit;
-BCP 47 language tags are mandatory from day one. TMX and XLIFF remain adjacent
-translation-workflow formats rather than being embedded into TermSpec.
+```text
+apps/studio/            React + TypeScript + Vite workbench
+src/termkit/spec/       TermSpec 0.2 semantic contracts and JSON Schema
+src/termkit/workspace/  Alembic-backed local application engine
+src/termkit/forge/      Reproducible candidate pipeline and plugin ports
+src/termkit/exchange/   CSV/XLSX/TBX/SKOS parsing and reconciliation plans
+src/termkit/runtime/    Resolution, QA, dependency locks, FTS and matcher compiler
+src/termkit/pack/       Canonical loading, validation and deterministic archives
+src/termkit/registry/   Verified immutable package installation
+src/termkit/server/     Local FastAPI and Studio API adapters
+examples/               Original test fixtures, never the production data catalog
+```
+
+Official original seed data lives in the separate sibling **TermKit-Packs**
+repository. Its dependency hierarchy covers mechanical engineering/hydraulics/
+construction machinery and machine learning/computer vision/object detection.
 
 ## Development
 
 ```bash
 uv run ruff check .
 uv run mypy src
+uv run python scripts/export_schemas.py --check
 uv run pytest --cov
-uv build
+cd apps/studio && bun run check && bun run test && bun run build
+cd ../.. && uv run python scripts/embed_studio_assets.py --check && uv build
 ```
 
-Read [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) before making
-structural changes.
+Read [CONTRIBUTING.md](CONTRIBUTING.md), [AGENTS.md](AGENTS.md), and
+[development.md](docs/development.md) before structural changes.
+
+## Trust and non-goals
 
-## Current non-goals
+TermPacks are untrusted data and never contain executable plugins. Reference-only
+or restricted sources cannot ship excerpts. Studio is local-only by default and
+must not be exposed directly to the public internet.
 
-- a terminology-management SaaS or marketplace UI;
-- bundled proprietary or scraped terminology data;
-- an LLM-generated glossary without evidence and review state;
-- arbitrary code execution from `.termpack` archives;
-- a custom TBX dialect, graph database, or vector database;
-- production multi-tenant hosting.
+TermKit does not bundle scraped/proprietary termbases, automatically approve
+machine proposals, invent a custom TBX dialect, or turn terminology curation
+into a chat-first AI product. Multi-tenant SaaS and a plugin marketplace remain
+outside the current security boundary.
 
 ## License