Optical Design 3.0.0

Optical Design 3.0.0

Learn with a measured lens walkthrough, inspect prescriptions with explicit import limits, and produce reviews whose acceptance and saved-candidate evidence agree.

Highlights

• Guided Cooke-triplet focus walkthrough: preserved source, bounded optimization, all configured fields and wavelengths measured after save/reload, and before/after plots with matching scales.
• Correct back focal length, separate image distance, and clearer paraxial metric definitions.
• Shared import assessment and numerical rejection of unconverted non-mm prescriptions.
• Consistent recipe/report schema with requirement checks, explicit evidence states, and complete metric-bound reload checks.
• Safer managed installation lifecycle: normal Python caches no longer block updates, one intact backup retained, and ownership-checked backup pruning.
• Explicit engine diagnostics, beginner prompts, corrected optical references, and evaluation rubrics excluded from installations.

Migration from 2.0.0

This is a major release because public metric semantics and report validation change.

• If you previously used bfl_mm as detector spacing, read image_distance_mm instead. back_focal_length_mm and the corrected bfl_mm alias now measure paraxial back focus from the last optical vertex.
• Gate inputs must be finite numeric requirements; a tolerance requires a target.
• Reloaded review evidence must uniquely cover every displayed metric, match its name/conditions/units, and agree with the reported value.
• Repository development evaluations moved to evals/ and are excluded from installed packages.

Full migration notes · Changelog

Try it

npx optical-design@3.0.0 install --agent codex
npx optical-design@3.0.0 walkthrough --out my-first-lens

Supported destinations: Claude Code, Codex, Cursor, OpenCode, and Hermes. Node.js 22+ and uv are required; the walkthrough fetches Python and pinned Optiland dependencies on first use.

Verification and scope

Local verification: 941 portable Python tests and 56 Node tests passed, with platform/native exclusions documented. Package lifecycle checks exercise all five installation destinations; the installed calculator and walkthrough preserve project outputs through update/uninstall. The packed audited demo passes.

Cross-platform CI results are attached to the release commit. No new native engine certification, cross-model uplift, or beginner participant study is claimed.

The npm archive is attached with SHA-256 checksums. Previous releases remain available for explicitly pinned workflows.

Post-publication verification: npm latest resolves to 3.0.0 and its archive matches the GitHub asset. The walkthrough fetched from npm preserved its source, passed all nine declared field/wavelength requirements, and improved worst sampled RMS spot radius from 85.03 to 18.76 µm after candidate save/reload.

Optical Design 2.0.0

2.0.0 — 2026-09-14

The skill now guides the coding agent instead of wrapping it: knowledge, recipes and
discipline in the skill, computation in code the agent writes against Optiland or
OpticStudio. The audited job runner remains as an optional mode with unchanged algorithms.

• Reframe the skill around guiding the coding agent: a one-screen SKILL.md with the
  workflow and discipline, an Optiland recipes reference with executable, tested snippets,
  an aberrations primer, a diagnosis template, a rewritten merit-function recipe, and
  rewritten microscopy and OCT design references.
• Add inspect_zmx.py (opens any OpticStudio export through Optiland and classifies its
  directives), first_order.py (paraxial gate with optional pass/fail spec) and
  render_review.py (summary.json plus PNGs to a self-contained review page).
• Add an eleven-form starting-point library in .zmx and Optiland JSON with commentary,
  five eval scenarios with checkable assertions, and a first-order ground-truth checker.
• Move the job-runner documentation under references/audited/ as the audited mode.
• Remove committed release-evidence trees (docs/research/, 98 MB of receipts and logs),
  internal planning documents (docs/superpowers/), the product brief and the deployment
  explainer from the main branch. Evidence stays available at the v1.0.0 and v1.1.0 tags.
• Move the brand guide to assets/brand/README.md; merge the example page into the quickstart.
• Add docs/roadmap/2026-09-14-adoption-review.md: an audit with a prioritized plan.

Upgrade

Run npx optical-design@2.0.0 update --agent codex (or your existing installer target). Existing optical algorithms remain available in the optional audited mode. References for that mode moved to references/audited/; update direct links and scripts that refer to the old documentation paths. Historical research receipts are retained at the v1 tags.

Verification and recovery

The release tarball contains 165 files; historical research trees, worktrees, caches and temporary outputs are excluded. See the attached SHA256 checksum and npm integrity receipt. Native OpticStudio requires its separately installed Windows engine and license; this release does not claim fresh native-engine validation on the release host.

For a regression, pin optical-design@1.1.0; maintainers can restore npm's latest tag to 1.1.0 without deleting this release.
Release checks: all 11 CI jobs passed on the tagged commit. Local package/demo, typecheck, lint and dependency audit passed. A local Python job timeout passed when rerun from identical source outside OneDrive; details are in verification.json.

npm status: optical-design@2.0.0 is published and is the latest release. A fresh public registry install passed, and its integrity matches the verified release tarball.

v1.1.0 — npm installer and public repository

Version 1.1.0 adds a versioned npm installer and a clearer public entry point for the existing sequential optical-design workflow.

Install

npx optical-design install

Choose Claude Code, Codex, Cursor, OpenCode, or Hermes. For noninteractive use, pass --agent codex (or the relevant agent). Installation is project-scoped; --global selects your user scope. Requires Node.js 22+.

npx optical-design doctor
npx optical-design demo --out my-first-lens

The demo uses uv and pinned Optiland dependencies, preserves the synthetic source, verifies the saved candidate, and writes an HTML review. It needs no OpticStudio license.

Changes

• Dependency-free CLI for install, update, uninstall, diagnostics, and a real portable demo. Managed installs detect edits, preserve user files, and retain update backups.
• Claude Code and Codex repository marketplace support, plus Cursor plugin metadata and direct skill installation across five agents.
• Original lens/focus branding, a task-based README, an actual computed example, concise installation and reference guides, and issue templates.
• Public-profile design informed by research into eight skill/optical repositories and MecAgent.

Verification

All 11 CI jobs passed at commit 82c7ef735c881b2d178e1786f719605989c0d0c4, including packed installer and portable-demo checks on Windows, macOS, and Linux. Fresh public npm installs passed for all five agents and the downloaded package completed the demo with saved-candidate acceptance.

The npm registry integrity matches the attached tarball. Native Claude Code installation/removal passed against the local release; native Codex installation/removal passed from GitHub at version 1.1.0 with all 76 skill files matching. The attached verification receipt records details and limits.

The optical algorithms and supported model scope are unchanged from 1.0.0. This remains a bounded sequential imaging workflow. Native OpticStudio needs Windows and an API license. Cursor UI installation and acceptance into public curated catalogs are not claimed.

Installation guide · npm package · Capabilities

Optical Design 1.0.0

Complete saved-prescription workflow for sequential imaging: inspect, define requirements and composite merit, make controlled edits, optimize, measure sensitivity, validate separately, and generate verified HTML/Markdown reviews.

• Weighted merit across fields, wavelengths and metrics, with per-term evidence and hard requirements.
• Expected-value radius/thickness edits; source preservation, saved reload and immutable artifact checks.
• Local sensitivity, bounded optimization, compensated tolerance evidence and independent validation settings.
• Native centered Standard conics and EvenAspheric surfaces with fixed A2–A16 coefficients; analytic/native sag checks.
• All engineering actions and review generation through owned MCP jobs, with exact input snapshots and reassessed receipts.
• Shipped installed-workflow scenarios and retained two-engine evidence.

Validation: 837 local Python tests passed (two platform-specific skips), seven package tests, lint and package checks; actual OpticStudio/Optiland MCP workflows; public npx skills add installation with all 76 tracked files matching the release commit and all 14 workflow calls passing. All nine hosted CI jobs passed: Python 3.11/3.13 on Windows/macOS/Linux, plus portable Optiland/MCP jobs on Windows/Linux.

Install:

npx skills add tangericm/optical-design

This installs the GitHub skill; no optical-design npm package is required. Native use needs a supported licensed OpticStudio installation. The supported workflow uses saved model copies, scalar analyses and explicit bounded radius/thickness changes. It does not include lens synthesis, non-sequential/stray-light design, thermal analysis or live GUI editing. The previously recorded real OCT Huygens/POP discrepancy remains unresolved.

See the README, compatibility record and docs/research/full-release/ for exact scope, receipts and limitations.