os-optics-kit 0.1.0__tar.gz

os_optics_kit-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+# Local runs and outputs (cases keep their project.json; generated runs stay out of Git)
+/run*/
+/run*-arrivals.csv
+/shots/
+/view.html
+/project.json
+/arrivals.csv
+/rays.jsonl
+cases/*/run*/
+cases/*/out/
+.DS_Store

os_optics_kit-0.1.0/AGENT_GUIDE.md

@@ -0,0 +1,79 @@
+# Agent guide
+
+os-optics-kit: tools, engine-reproducible cases and skills for the OS Optics engine (`os-optics`).
+Install with `python -m pip install "os-optics[protected]" os-optics-kit` (Python 3.11+); kit 0.1.x
+requires `os-optics>=0.12,<0.13`. Engine guide:
+[os-optics AGENT_GUIDE](https://github.com/JunLin615/os-optics/blob/main/AGENT_GUIDE.md).
+
+## Load the skills
+
+```bash
+os-optics-kit skills list
+os-optics-kit skills show NAME
+os-optics-kit skills install --dest DIR
+```
+
+`skills list` prints the index (name, description, command, requirement) as compact JSON. Read one
+skill before using its command. `skills install` copies the skill directories and `skills.json` into
+DIR, the skills directory of your agent host; it never overwrites a different file without `--force`.
+
+## Route by task
+
+| Task | Skill / command |
+| --- | --- |
+| Start from a worked design | `run-case`: `os-optics-kit cases list`, `cases copy NAME --dest .`, `cases verify NAME` |
+| Read a run before deciding | `summary RUN` |
+| Discover IDs, units, axes; edit by ID | `edit P.json --describe --ids ID`; `edit P.json --edits OPS.json --out NEW.json --run RUN` |
+| Explore one or two parameters | `sweep SPEC.json --base P.json --out STUDY` |
+| Explain what an edit changed | `compare RUN_A RUN_B --project CURRENT.json --out CMP` |
+| Plots and a report | `plot sweep STUDY --y target:ID`; `report STUDY --project CURRENT.json` |
+| Sensitivity, tolerance | `sensitivity SPEC.json --out DIR`; `tolerance SPEC.json --out DIR` |
+| Catalog parts | `candidates --category ... --wavelength-nm ...` |
+| Detector CSV data | `measurements DATA.csv --x ... --signal ... --out DIR` |
+| Share a design or helper | `contrib-case`, `contrib-tool` |
+
+Each command is `os-optics-kit <command>`; `--help` holds its full specification.
+[Workflow recipes](docs/workflow-recipes.md) give spec keys, outputs and error codes.
+Cases `expansion-focus`, `polarization-control` and `mirror-alignment` include a parameterized
+`workflow.py` (`--list-parameters`, unit-bearing inputs such as `--gap-error-mm 250um`,
+`--study NAME=START..STOP:COUNT`, `--no-studies`).
+
+## Interpret before deciding
+
+Read computation completion, quantity validity, target assessment and freshness separately. Engine
+assessments are `MET`, `UNMET`, `INDETERMINATE` or `NOT_APPLICABLE`. A bounded quantity is an
+interval; an unrelated unavailable quantity does not invalidate every result. No configured target
+means no requirement was assessed.
+
+Study `PASS`/`FAIL` classes summarize the selected targets. Keep
+every sample, including invalid, partial and indeterminate ones. Objective validity and feasibility
+are separate; report `NO_FEASIBLE` when no sample meets the constraints. Fractions state their
+denominator; a tolerance fraction describes simulated samples under the declared distributions.
+
+Saved results keep their identities after edits. `compare` and `os-optics results freshness RUN
+--project P` report `CURRENT`, `HISTORICAL` or `UNDETERMINED` with reasons (`PHYSICS_CHANGED`,
+`TARGETS_CHANGED`, ...). A historical result describes the earlier design; rerun when the task needs
+the edited one.
+
+Exit codes: 0 completed or PASS; 1 FAIL, `NO_FEASIBLE`, `NO_MATCH` or a case mismatch; 2 UNKNOWN or
+`INCOMPLETE`; 3 OUT_OF_MODEL; 4 refused input, with a JSON error on stderr. Stdout is compact JSON;
+details stay in files.
+
+## Inputs and recovery
+
+Establish wavelength (nm), power (W), Gaussian 1/e² intensity radius and positions (mm), object IDs,
+poses and the user's actual target bounds. Coordinates are right-handed; quaternions are
+`[w, x, y, z]`. Read `local_axes` before moving along a local axis.
+
+Inputs are never modified; an existing output is refused (`OUTPUT_EXISTS`) unless `--overwrite`.
+Invalid edits are refused atomically. Repeating an identical `edit` returns `already_applied`;
+`--expect-base-hash` refuses a changed base. Set both a study's `max_evaluations` and the Project's
+compute budget, and inspect limited or partial results before raising a limit. Report commands,
+versions, units, selected assessments, freshness and artifact paths.
+
+## Contribute
+
+`os-optics-kit skills show contrib-case` or `contrib-tool`, then `os-optics-kit contrib case
+P.json --name NAME --dry-run`. The user's own GitHub account opens the pull request (`--open-pr`);
+without it the command leaves a bundle with the patch. See
+[contributing with an agent](docs/contributing-with-an-agent.md).

os_optics_kit-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,120 @@
+# Contributing to os-optics-kit
+
+os-optics-kit collects tools, engine-reproducible cases and agent skills for
+[OS Optics](https://github.com/JunLin615/os-optics). Contributions are welcome as pull requests to this
+repository. You open them from your own fork with your own GitHub account, by hand or through your agent.
+
+Engine problems (the `os-optics` commands, simulation results, the optical catalog) go to the
+[os-optics issue tracker](https://github.com/JunLin615/os-optics/issues).
+
+## What you can contribute
+
+| Contribution | Lives in | Starts from |
+| --- | --- | --- |
+| Case: a design that runs on the verified engine and catalog, with its expected outcomes | `cases/<name>/` | `os-optics-kit contrib case` or [the case format](docs/case-format.md) |
+| Tool: a shared helper, exposed as an `os-optics-kit` command | `tools/os_optics_kit/` | `os-optics-kit contrib tool` |
+| Skill: the page an agent reads to use a tool or follow a workflow | `skills/<name>/SKILL.md` | `templates/SKILL.md` |
+| Documentation, fixes, CI | anywhere | an issue or a pull request |
+
+A helper that only one case uses stays in that case's directory; tools never depend on cases.
+
+## With an agent
+
+The contribution commands do the preparation for you or your agent:
+
+```bash
+os-optics-kit contrib case my_design.json --name my-case --dry-run   # check and preview locally
+os-optics-kit contrib case my_design.json --name my-case --open-pr  # fork, push and open the pull request
+os-optics-kit contrib tool my_helper.py --name my-tool --dry-run
+```
+
+`contrib case` normalizes the Project, pins the engine and catalog versions, runs `project check`, `project run`
+and `results targets`, renders the images, writes `CASE.md`, `README.md` and `expected.json`, and produces a
+patch with a pull-request description. `--open-pr` uses your own `gh` login; without it you get a bundle directory
+with the patch, which you can apply and push yourself. Step-by-step instructions, including what to tell your
+agent, are in [Contributing with an agent](docs/contributing-with-an-agent.md).
+
+## By hand
+
+1. Fork the repository and create a branch.
+2. Set up an environment with the engine version in [`baseline.json`](baseline.json):
+
+   ```bash
+   python -m venv .venv
+   . .venv/bin/activate            # Windows: .venv\Scripts\activate
+   python -m pip install --upgrade pip
+   python -m pip install "os-optics[protected]==0.12.0" matplotlib
+   python -m pip install --no-deps -e .
+   python -m pip install --group dev
+   ```
+
+3. Make the change, then run the checks CI runs:
+
+   ```bash
+   python scripts/check_repo.py
+   ruff check .
+   mypy
+   python -m pytest
+   os-optics-kit skills index --check     # after changing skills: --write, then commit skills.json
+   os-optics-kit cases index --check      # after changing cases:  --write, then commit cases.json
+   os-optics-kit cases verify my-case     # for every case you added or changed
+   ```
+
+4. Commit with a sign-off (`git commit -s`), push to your fork and open a pull request.
+
+## Sign-off (DCO)
+
+Every commit needs a `Signed-off-by:` line with your name and the email of the commit author. It certifies the
+[Developer Certificate of Origin](https://developercertificate.org/): you wrote the change or have the right to
+submit it under the project's license. `git commit -s` adds the line. To sign off commits you already made on a
+branch, run `git rebase --signoff main` and force-push the branch.
+
+## What CI checks
+
+| Check | Runs on |
+| --- | --- |
+| Lint (`ruff`) and types (`mypy`) | every pull request |
+| Unit tests without the engine, on each Python version in `baseline.json` | every pull request |
+| `scripts/check_repo.py`: Markdown links resolve, no file over 1 MiB and no image over 400 KiB, no run outputs, no machine-specific paths or secrets, JSON parses, `baseline.json` agrees with the package, English and Simplified Chinese pages come in pairs | every pull request |
+| `skills.json` and `cases.json` match the skills and cases | every pull request |
+| Wheel and source build, `twine check`, contents check, clean `--no-deps` install and command smoke test | every pull request |
+| DCO sign-off of every commit | every pull request |
+| Full test suite, tool workflows and `cases verify` on the published os-optics release and catalog snapshot in `baseline.json`: the cases a pull request changes, all cases on `main` | every pull request, once that os-optics release is on PyPI |
+| Linux, Windows and macOS on every Python version, all cases, and the newest os-optics release as a candidate | weekly |
+| CodeQL | every pull request and weekly |
+
+## Acceptance criteria
+
+A case is accepted when:
+
+- it follows [the case format](docs/case-format.md): `project.json`, `CASE.md` (at most 700 tokens), `README.md`,
+  `expected.json`, and at most four images of at most 400 KiB each, rendered by the engine from the case's own run;
+- `os-optics-kit cases verify NAME` reproduces `expected.json` on the engine version and catalog release it
+  declares, which are the ones in `baseline.json`;
+- it shows something the collection does not show yet, and its README explains it in a few paragraphs;
+- it contains only material you can publish under the MIT license: no private, supplier or customer data, no
+  run directories or 3D scene files.
+
+A tool is accepted when:
+
+- more than one case or workflow can use it;
+- it is a module of `tools/os_optics_kit/` with `main(argv) -> int`, registered in the command table, printing
+  compact JSON and using the kit's exit codes;
+- `os-optics-kit <command> --help` works without the engine installed (the engine is imported inside functions);
+- it comes with a skill page of the same name (at most 900 tokens) and tests under `tests/`.
+
+A skill page follows `templates/SKILL.md`: the required front matter and sections, no host-specific API, at most
+900 tokens.
+
+## Versions
+
+`baseline.json` records the os-optics range the kit supports, the os-optics version it was verified with, and
+the catalog release (with its SHA-256) the cases run on. Every case declares the engine and catalog it was
+verified with. When a new catalog release or engine version changes a case's outcome, the case is re-verified and
+its `expected.json`, `CASE.md` and images are updated in the same pull request that moves `baseline.json`.
+[Engine alignment](docs/engine-alignment.md) describes the checks behind this.
+
+## Conduct and license
+
+Participation follows the [Code of Conduct](CODE_OF_CONDUCT.md). Contributions are released under the
+[MIT License](LICENSE). Security issues: see [SECURITY.md](SECURITY.md).

os_optics_kit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenSci and the os-optics-kit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

os_optics_kit-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.5
+Name: os-optics-kit
+Version: 0.1.0
+Summary: Tools, engine-reproducible cases and vendor-neutral agent skills for OS Optics (os-optics).
+Project-URL: Homepage, https://opensci-optics.com/
+Project-URL: Documentation, https://github.com/JunLin615/os-optics-kit#readme
+Project-URL: Source, https://github.com/JunLin615/os-optics-kit
+Project-URL: Issues, https://github.com/JunLin615/os-optics-kit/issues
+Author: OpenSci
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent skills,optical design,optics,os-optics,parameter sweep,tolerance analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.11
+Requires-Dist: os-optics<0.13,>=0.12
+Provides-Extra: plot
+Requires-Dist: matplotlib<4,>=3.10; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# os-optics-kit
+
+**Tools, engine-reproducible cases and agent skills for OS Optics.**
+
+English · [简体中文](https://github.com/JunLin615/os-optics-kit/blob/main/README.zh-CN.md)
+
+[![PyPI](https://img.shields.io/pypi/v/os-optics-kit.svg)](https://pypi.org/project/os-optics-kit/)
+[![Python](https://img.shields.io/pypi/pyversions/os-optics-kit.svg)](https://pypi.org/project/os-optics-kit/)
+
+os-optics-kit builds on the [OS Optics](https://github.com/JunLin615/os-optics) engine. It provides one command,
+`os-optics-kit`, with tools that edit Projects by ID, sweep parameters, compare saved runs, plot, report, estimate
+sensitivity and tolerance, select catalog parts and analyze detector measurements; a collection of cases, designs
+that rerun on the engine and compare with their recorded outcome; and a vendor-neutral skill page for each tool,
+which any coding agent can load.
+
+| Name | Where | Contents |
+| --- | --- | --- |
+| [`os-optics`](https://pypi.org/project/os-optics/) | PyPI | The engine: optical catalog, simulation, results and 3D view |
+| [`os-optics-kit`](https://pypi.org/project/os-optics-kit/) | PyPI | Tools, cases and agent skills built on the engine |
+| [`os-optics`](https://github.com/JunLin615/os-optics) | GitHub | Product documentation and feedback |
+| [`os-optics-kit`](https://github.com/JunLin615/os-optics-kit) | GitHub | This repository: tools, cases, skills and contributions |
+
+**[Agent guide](https://github.com/JunLin615/os-optics-kit/blob/main/AGENT_GUIDE.md) · [Design studies](https://github.com/JunLin615/os-optics-kit/blob/main/docs/en/workflows.md) · [Measurements](https://github.com/JunLin615/os-optics-kit/blob/main/docs/en/measurements.md) · [External tools](https://github.com/JunLin615/os-optics-kit/blob/main/docs/en/interop.md) · [Workflow recipes](https://github.com/JunLin615/os-optics-kit/blob/main/docs/workflow-recipes.md) · [Contributing](https://github.com/JunLin615/os-optics-kit/blob/main/CONTRIBUTING.md)**
+
+## Install
+
+```bash
+python -m pip install "os-optics[protected]" os-optics-kit
+os-optics doctor
+```
+
+Python 3.11 or newer. Plots need the `plot` extra: `python -m pip install "os-optics-kit[plot]"`. Cases that use
+catalog components need the catalog: `os-optics catalog sync`. The engine's
+[installation guide](https://github.com/JunLin615/os-optics/blob/main/docs/en/installation.md) covers virtual
+environments and upgrades.
+
+## Quick start
+
+```bash
+os-optics-kit skills list
+os-optics-kit skills install --dest SKILLS_DIR
+os-optics-kit cases list
+os-optics-kit cases copy ideal-lens-focus --dest .
+os-optics-kit cases verify ideal-lens-focus
+cd ideal-lens-focus
+os-optics project run project.json --out-dir run
+os-optics-kit summary run
+```
+
+`skills list` prints the skill index as compact JSON; `skills install` copies the skill pages into the skills
+directory of your agent host (`SKILLS_DIR`). The cases ship inside the package, so `cases copy` and `cases verify`
+work without a clone; `verify` reruns the case and compares the run status and every target assessment with the
+recorded outcome. `os-optics-kit <command> --help` describes every command.
+
+## Cases
+
+| Case | What it shows | Catalog |
+| --- | --- | --- |
+| [beam-expander](https://github.com/JunLin615/os-optics-kit/tree/main/cases/beam-expander) | Catalog beam expander: swap a lens, sweep its spacing, restore collimation | yes |
+| [ideal-lens-focus](https://github.com/JunLin615/os-optics-kit/tree/main/cases/ideal-lens-focus) | Gaussian focus of an ideal thin lens | no |
+| [expansion-focus](https://github.com/JunLin615/os-optics-kit/tree/main/cases/expansion-focus) | Beam expansion and focusing workflow with sensitivity and tolerance studies | no |
+| [polarization-control](https://github.com/JunLin615/os-optics-kit/tree/main/cases/polarization-control) | Polarization control with a half-wave plate and a polarizer | no |
+| [mirror-alignment](https://github.com/JunLin615/os-optics-kit/tree/main/cases/mirror-alignment) | Beam position and pointing after a fold mirror | no |
+| [detector-measurements](https://github.com/JunLin615/os-optics-kit/tree/main/cases/detector-measurements) | Detector linearity and reference-channel normalization | no |
+| [interop-optimization](https://github.com/JunLin615/os-optics-kit/tree/main/cases/interop-optimization) | External optimization and Sobol tolerance of a beam expander | no |
+| [interop-diffraction](https://github.com/JunLin615/os-optics-kit/tree/main/cases/interop-diffraction) | Diffraction at a declared stop, handed off to external codes | no |
+| [interop-quantum](https://github.com/JunLin615/os-optics-kit/tree/main/cases/interop-quantum) | Hong-Ou-Mandel interference from the linear optical network export | no |
+| [interop-metasurface](https://github.com/JunLin615/os-optics-kit/tree/main/cases/interop-metasurface) | Metasurface lens as a tabulated virtual component | no |
+
+Each case holds `project.json` (the Project with its targets), `CASE.md` (for agents), an illustrated `README.md`
+and `expected.json` (the verified outcome), plus its own scripts, study specs or data. See the
+[case format](https://github.com/JunLin615/os-optics-kit/blob/main/docs/case-format.md).
+
+## Tools and skills
+
+| Skill | Command | Use it to |
+| --- | --- | --- |
+| `summary` | `os-optics-kit summary` | Read a saved run into one compact JSON document with an exit code per outcome |
+| `edit` | `os-optics-kit edit` | List a Project's objects and apply edits by ID, checked by the engine and written atomically |
+| `sweep` | `os-optics-kit sweep` | Run a bounded one- or two-parameter sweep, every sample saved and counted |
+| `compare` | `os-optics-kit compare` | Compare saved runs or sweep samples by target and plane ID, with freshness |
+| `plot` | `os-optics-kit plot` | Draw sweep curves, heatmaps, power distributions, bar charts and histograms |
+| `report` | `os-optics-kit report` | Assemble a Markdown and JSON report with counts, diagnostics and artifact hashes |
+| `sensitivity` | `os-optics-kit sensitivity` | Rank design parameters by finite-difference sensitivity at two step sizes |
+| `tolerance` | `os-optics-kit tolerance` | Run a seeded tolerance study under declared distributions |
+| `candidates` | `os-optics-kit candidates` | List catalog products that pass explicit filters, sorted by closeness to a value |
+| `measurements` | `os-optics-kit measurements` | Subtract backgrounds, normalize by a reference channel and fit detector CSV data |
+| `run-case` | `os-optics-kit cases` | Find, copy, run, check and adapt a case |
+| `contrib-case` | `os-optics-kit contrib case` | Turn a finished design into a pull-request-ready case |
+| `contrib-tool` | `os-optics-kit contrib tool` | Package a helper as a kit command with its skill page and tests |
+
+`os-optics-kit skills show NAME` prints a skill page; [`skills.json`](https://github.com/JunLin615/os-optics-kit/blob/main/skills.json) indexes them. Tools are also
+importable (`import os_optics_kit`), and `python -m os_optics_kit <command>` runs the same commands.
+
+## Version alignment
+
+os-optics-kit 0.1.x requires `os-optics>=0.12,<0.13` and was verified with os-optics 0.12.0 and catalog release
+2026-10-28.1 ([`baseline.json`](https://github.com/JunLin615/os-optics-kit/blob/main/baseline.json)). Each case records the engine and catalog release it was verified
+with. See [case format](https://github.com/JunLin615/os-optics-kit/blob/main/docs/case-format.md) and [engine alignment](https://github.com/JunLin615/os-optics-kit/blob/main/docs/engine-alignment.md).
+
+## Contributing
+
+Cases, tools, skills and documentation are welcome as pull requests. An agent contributes with the user's own
+GitHub account: `os-optics-kit contrib case` and `os-optics-kit contrib tool` verify the contribution and open the
+pull request, or stop at a bundle with the patch to submit later. See [CONTRIBUTING.md](https://github.com/JunLin615/os-optics-kit/blob/main/CONTRIBUTING.md) and
+[contributing with an agent](https://github.com/JunLin615/os-optics-kit/blob/main/docs/contributing-with-an-agent.md). Engine questions and bug reports go to the
+[os-optics issue tracker](https://github.com/JunLin615/os-optics/issues).
+
+## License
+
+os-optics-kit is released under the [MIT License](https://github.com/JunLin615/os-optics-kit/blob/main/LICENSE). The engine, os-optics, is distributed under its own
+license.

os_optics_kit-0.1.0/README.md

@@ -0,0 +1,112 @@
+# os-optics-kit
+
+**Tools, engine-reproducible cases and agent skills for OS Optics.**
+
+English · [简体中文](https://github.com/JunLin615/os-optics-kit/blob/main/README.zh-CN.md)
+
+[![PyPI](https://img.shields.io/pypi/v/os-optics-kit.svg)](https://pypi.org/project/os-optics-kit/)
+[![Python](https://img.shields.io/pypi/pyversions/os-optics-kit.svg)](https://pypi.org/project/os-optics-kit/)
+
+os-optics-kit builds on the [OS Optics](https://github.com/JunLin615/os-optics) engine. It provides one command,
+`os-optics-kit`, with tools that edit Projects by ID, sweep parameters, compare saved runs, plot, report, estimate
+sensitivity and tolerance, select catalog parts and analyze detector measurements; a collection of cases, designs
+that rerun on the engine and compare with their recorded outcome; and a vendor-neutral skill page for each tool,
+which any coding agent can load.
+
+| Name | Where | Contents |
+| --- | --- | --- |
+| [`os-optics`](https://pypi.org/project/os-optics/) | PyPI | The engine: optical catalog, simulation, results and 3D view |
+| [`os-optics-kit`](https://pypi.org/project/os-optics-kit/) | PyPI | Tools, cases and agent skills built on the engine |
+| [`os-optics`](https://github.com/JunLin615/os-optics) | GitHub | Product documentation and feedback |
+| [`os-optics-kit`](https://github.com/JunLin615/os-optics-kit) | GitHub | This repository: tools, cases, skills and contributions |
+
+**[Agent guide](https://github.com/JunLin615/os-optics-kit/blob/main/AGENT_GUIDE.md) · [Design studies](https://github.com/JunLin615/os-optics-kit/blob/main/docs/en/workflows.md) · [Measurements](https://github.com/JunLin615/os-optics-kit/blob/main/docs/en/measurements.md) · [External tools](https://github.com/JunLin615/os-optics-kit/blob/main/docs/en/interop.md) · [Workflow recipes](https://github.com/JunLin615/os-optics-kit/blob/main/docs/workflow-recipes.md) · [Contributing](https://github.com/JunLin615/os-optics-kit/blob/main/CONTRIBUTING.md)**
+
+## Install
+
+```bash
+python -m pip install "os-optics[protected]" os-optics-kit
+os-optics doctor
+```
+
+Python 3.11 or newer. Plots need the `plot` extra: `python -m pip install "os-optics-kit[plot]"`. Cases that use
+catalog components need the catalog: `os-optics catalog sync`. The engine's
+[installation guide](https://github.com/JunLin615/os-optics/blob/main/docs/en/installation.md) covers virtual
+environments and upgrades.
+
+## Quick start
+
+```bash
+os-optics-kit skills list
+os-optics-kit skills install --dest SKILLS_DIR
+os-optics-kit cases list
+os-optics-kit cases copy ideal-lens-focus --dest .
+os-optics-kit cases verify ideal-lens-focus
+cd ideal-lens-focus
+os-optics project run project.json --out-dir run
+os-optics-kit summary run
+```
+
+`skills list` prints the skill index as compact JSON; `skills install` copies the skill pages into the skills
+directory of your agent host (`SKILLS_DIR`). The cases ship inside the package, so `cases copy` and `cases verify`
+work without a clone; `verify` reruns the case and compares the run status and every target assessment with the
+recorded outcome. `os-optics-kit <command> --help` describes every command.
+
+## Cases
+
+| Case | What it shows | Catalog |
+| --- | --- | --- |
+| [beam-expander](https://github.com/JunLin615/os-optics-kit/tree/main/cases/beam-expander) | Catalog beam expander: swap a lens, sweep its spacing, restore collimation | yes |
+| [ideal-lens-focus](https://github.com/JunLin615/os-optics-kit/tree/main/cases/ideal-lens-focus) | Gaussian focus of an ideal thin lens | no |
+| [expansion-focus](https://github.com/JunLin615/os-optics-kit/tree/main/cases/expansion-focus) | Beam expansion and focusing workflow with sensitivity and tolerance studies | no |
+| [polarization-control](https://github.com/JunLin615/os-optics-kit/tree/main/cases/polarization-control) | Polarization control with a half-wave plate and a polarizer | no |
+| [mirror-alignment](https://github.com/JunLin615/os-optics-kit/tree/main/cases/mirror-alignment) | Beam position and pointing after a fold mirror | no |
+| [detector-measurements](https://github.com/JunLin615/os-optics-kit/tree/main/cases/detector-measurements) | Detector linearity and reference-channel normalization | no |
+| [interop-optimization](https://github.com/JunLin615/os-optics-kit/tree/main/cases/interop-optimization) | External optimization and Sobol tolerance of a beam expander | no |
+| [interop-diffraction](https://github.com/JunLin615/os-optics-kit/tree/main/cases/interop-diffraction) | Diffraction at a declared stop, handed off to external codes | no |
+| [interop-quantum](https://github.com/JunLin615/os-optics-kit/tree/main/cases/interop-quantum) | Hong-Ou-Mandel interference from the linear optical network export | no |
+| [interop-metasurface](https://github.com/JunLin615/os-optics-kit/tree/main/cases/interop-metasurface) | Metasurface lens as a tabulated virtual component | no |
+
+Each case holds `project.json` (the Project with its targets), `CASE.md` (for agents), an illustrated `README.md`
+and `expected.json` (the verified outcome), plus its own scripts, study specs or data. See the
+[case format](https://github.com/JunLin615/os-optics-kit/blob/main/docs/case-format.md).
+
+## Tools and skills
+
+| Skill | Command | Use it to |
+| --- | --- | --- |
+| `summary` | `os-optics-kit summary` | Read a saved run into one compact JSON document with an exit code per outcome |
+| `edit` | `os-optics-kit edit` | List a Project's objects and apply edits by ID, checked by the engine and written atomically |
+| `sweep` | `os-optics-kit sweep` | Run a bounded one- or two-parameter sweep, every sample saved and counted |
+| `compare` | `os-optics-kit compare` | Compare saved runs or sweep samples by target and plane ID, with freshness |
+| `plot` | `os-optics-kit plot` | Draw sweep curves, heatmaps, power distributions, bar charts and histograms |
+| `report` | `os-optics-kit report` | Assemble a Markdown and JSON report with counts, diagnostics and artifact hashes |
+| `sensitivity` | `os-optics-kit sensitivity` | Rank design parameters by finite-difference sensitivity at two step sizes |
+| `tolerance` | `os-optics-kit tolerance` | Run a seeded tolerance study under declared distributions |
+| `candidates` | `os-optics-kit candidates` | List catalog products that pass explicit filters, sorted by closeness to a value |
+| `measurements` | `os-optics-kit measurements` | Subtract backgrounds, normalize by a reference channel and fit detector CSV data |
+| `run-case` | `os-optics-kit cases` | Find, copy, run, check and adapt a case |
+| `contrib-case` | `os-optics-kit contrib case` | Turn a finished design into a pull-request-ready case |
+| `contrib-tool` | `os-optics-kit contrib tool` | Package a helper as a kit command with its skill page and tests |
+
+`os-optics-kit skills show NAME` prints a skill page; [`skills.json`](https://github.com/JunLin615/os-optics-kit/blob/main/skills.json) indexes them. Tools are also
+importable (`import os_optics_kit`), and `python -m os_optics_kit <command>` runs the same commands.
+
+## Version alignment
+
+os-optics-kit 0.1.x requires `os-optics>=0.12,<0.13` and was verified with os-optics 0.12.0 and catalog release
+2026-10-28.1 ([`baseline.json`](https://github.com/JunLin615/os-optics-kit/blob/main/baseline.json)). Each case records the engine and catalog release it was verified
+with. See [case format](https://github.com/JunLin615/os-optics-kit/blob/main/docs/case-format.md) and [engine alignment](https://github.com/JunLin615/os-optics-kit/blob/main/docs/engine-alignment.md).
+
+## Contributing
+
+Cases, tools, skills and documentation are welcome as pull requests. An agent contributes with the user's own
+GitHub account: `os-optics-kit contrib case` and `os-optics-kit contrib tool` verify the contribution and open the
+pull request, or stop at a bundle with the patch to submit later. See [CONTRIBUTING.md](https://github.com/JunLin615/os-optics-kit/blob/main/CONTRIBUTING.md) and
+[contributing with an agent](https://github.com/JunLin615/os-optics-kit/blob/main/docs/contributing-with-an-agent.md). Engine questions and bug reports go to the
+[os-optics issue tracker](https://github.com/JunLin615/os-optics/issues).
+
+## License
+
+os-optics-kit is released under the [MIT License](https://github.com/JunLin615/os-optics-kit/blob/main/LICENSE). The engine, os-optics, is distributed under its own
+license.

os_optics_kit-0.1.0/README.zh-CN.md

@@ -0,0 +1,106 @@
+# os-optics-kit
+
+**OS Optics 的工具、可由引擎复现的案例和 Agent 技能。**
+
+[English](README.md) · 简体中文
+
+[![PyPI](https://img.shields.io/pypi/v/os-optics-kit.svg)](https://pypi.org/project/os-optics-kit/)
+[![Python](https://img.shields.io/pypi/pyversions/os-optics-kit.svg)](https://pypi.org/project/os-optics-kit/)
+
+os-optics-kit 基于 [OS Optics](https://github.com/JunLin615/os-optics) 引擎，提供一个命令 `os-optics-kit`：
+其中的工具可以按标识修改 Project、扫描参数、比较已保存的运行、绘图、生成报告、估计灵敏度和公差、
+挑选目录元件以及分析探测器测量数据；一组案例，即可在引擎上重新运行并与记录结果比较的设计；以及每个工具
+对应的一份与厂商无关的技能说明，任何编程 Agent 都可以加载。
+
+| 名称 | 位置 | 内容 |
+| --- | --- | --- |
+| [`os-optics`](https://pypi.org/project/os-optics/) | PyPI | 引擎：光学元件目录、仿真、结果与三维视图 |
+| [`os-optics-kit`](https://pypi.org/project/os-optics-kit/) | PyPI | 基于引擎的工具、案例和 Agent 技能 |
+| [`os-optics`](https://github.com/JunLin615/os-optics) | GitHub | 产品文档与问题反馈 |
+| [`os-optics-kit`](https://github.com/JunLin615/os-optics-kit) | GitHub | 本仓库：工具、案例、技能与贡献 |
+
+**[Agent 指南（英文）](AGENT_GUIDE.md) · [设计研究](docs/zh-CN/workflows.md) · [测量数据](docs/zh-CN/measurements.md) · [外部工具](docs/zh-CN/interop.md) · [工作流程步骤（英文）](docs/workflow-recipes.md) · [参与贡献（英文）](CONTRIBUTING.md)**
+
+## 安装
+
+```bash
+python -m pip install "os-optics[protected]" os-optics-kit
+os-optics doctor
+```
+
+需要 Python 3.11 及以上版本。绘图需要 `plot` 扩展：`python -m pip install "os-optics-kit[plot]"`。
+使用目录元件的案例需要光学元件目录：`os-optics catalog sync`。虚拟环境和升级方法见引擎的
+[安装指南](https://github.com/JunLin615/os-optics/blob/main/docs/zh-CN/installation.md)。
+
+## 快速开始
+
+```bash
+os-optics-kit skills list
+os-optics-kit skills install --dest SKILLS_DIR
+os-optics-kit cases list
+os-optics-kit cases copy ideal-lens-focus --dest .
+os-optics-kit cases verify ideal-lens-focus
+cd ideal-lens-focus
+os-optics project run project.json --out-dir run
+os-optics-kit summary run
+```
+
+`skills list` 以紧凑 JSON 输出技能索引；`skills install` 把技能说明复制到 Agent 宿主的技能目录
+（`SKILLS_DIR`）。案例随软件包一起安装，因此 `cases copy` 和 `cases verify` 无需克隆仓库；`verify`
+重新运行案例，并将运行状态和每个目标判定与记录结果比较。`os-optics-kit <命令> --help` 说明每个命令。
+
+## 案例
+
+| 案例 | 内容 | 目录 |
+| --- | --- | --- |
+| [beam-expander](cases/beam-expander) | 目录元件扩束器：更换透镜、扫描间距、恢复准直 | 是 |
+| [ideal-lens-focus](cases/ideal-lens-focus) | 理想薄透镜的高斯聚焦 | 否 |
+| [expansion-focus](cases/expansion-focus) | 扩束与聚焦工作流程，含灵敏度和公差研究 | 否 |
+| [polarization-control](cases/polarization-control) | 用半波片和偏振器控制偏振 | 否 |
+| [mirror-alignment](cases/mirror-alignment) | 折返镜后的光束位置和指向 | 否 |
+| [detector-measurements](cases/detector-measurements) | 探测器线性度与参考通道归一化 | 否 |
+| [interop-optimization](cases/interop-optimization) | 扩束器的外部优化与 Sobol 公差分析 | 否 |
+| [interop-diffraction](cases/interop-diffraction) | 声明光阑处的衍射，交给外部程序计算 | 否 |
+| [interop-quantum](cases/interop-quantum) | 基于线性光学网络导出的 Hong-Ou-Mandel 干涉 | 否 |
+| [interop-metasurface](cases/interop-metasurface) | 作为表格化虚拟元件的超表面透镜 | 否 |
+
+每个案例包含 `project.json`（带目标的 Project）、`CASE.md`（供 Agent 阅读）、带插图的 `README.md`
+和 `expected.json`（验证结果），以及案例自己的脚本、研究规格或数据。见[案例格式（英文）](docs/case-format.md)。
+
+## 工具与技能
+
+| 技能 | 命令 | 用途 |
+| --- | --- | --- |
+| `summary` | `os-optics-kit summary` | 把已保存的运行读成一个紧凑 JSON 文档，并按结果给出退出码 |
+| `edit` | `os-optics-kit edit` | 列出 Project 中的对象，按标识修改，由引擎检查并原子写入 |
+| `sweep` | `os-optics-kit sweep` | 运行有界的单参数或双参数扫描，保存并统计每个样本 |
+| `compare` | `os-optics-kit compare` | 按目标和平面标识比较已保存的运行或扫描样本，并给出时效 |
+| `plot` | `os-optics-kit plot` | 绘制扫描曲线、热图、功率分布、条形图和直方图 |
+| `report` | `os-optics-kit report` | 生成 Markdown 和 JSON 报告，含计数、诊断信息和产物哈希 |
+| `sensitivity` | `os-optics-kit sensitivity` | 以两种步长的有限差分灵敏度对设计参数排序 |
+| `tolerance` | `os-optics-kit tolerance` | 在声明的分布下运行带种子的公差研究 |
+| `candidates` | `os-optics-kit candidates` | 列出满足明确筛选条件的目录产品，按与给定值的接近程度排序 |
+| `measurements` | `os-optics-kit measurements` | 扣除背景、按参考通道归一化并拟合探测器 CSV 数据 |
+| `run-case` | `os-optics-kit cases` | 查找、复制、运行、核对并修改案例 |
+| `contrib-case` | `os-optics-kit contrib case` | 把完成的设计整理成可直接提交拉取请求的案例 |
+| `contrib-tool` | `os-optics-kit contrib tool` | 把辅助脚本打包为套件命令，附技能说明和测试 |
+
+`os-optics-kit skills show NAME` 输出一份技能说明；[`skills.json`](skills.json) 是技能索引。工具也可以
+在 Python 中导入（`import os_optics_kit`），`python -m os_optics_kit <命令>` 运行同样的命令。
+
+## 版本对应
+
+os-optics-kit 0.1.x 需要 `os-optics>=0.12,<0.13`，已在 os-optics 0.12.0 和目录版本 2026-10-28.1 上验证
+（[`baseline.json`](baseline.json)）。每个案例记录验证时使用的引擎和目录版本。见
+[案例格式（英文）](docs/case-format.md)和[引擎对齐（英文）](docs/engine-alignment.md)。
+
+## 参与贡献
+
+欢迎以拉取请求提交案例、工具、技能和文档。Agent 使用用户自己的 GitHub 账号贡献：
+`os-optics-kit contrib case` 和 `os-optics-kit contrib tool` 验证贡献内容并打开拉取请求，或生成含补丁的
+文件包，供之后提交。见 [CONTRIBUTING.md](CONTRIBUTING.md) 和[用 Agent 参与贡献（英文）](docs/contributing-with-an-agent.md)。
+引擎相关的问题和缺陷报告请提交到 [os-optics 问题反馈](https://github.com/JunLin615/os-optics/issues)。
+
+## 许可证
+
+os-optics-kit 采用 [MIT 许可证](LICENSE)。引擎 os-optics 按其自身的许可证分发。