Agent environments (OpenClaw, Claude Code, Codex) assume users delegate
credentials to the agent. sops+age added setup friction without real
security benefit since the agent decrypts on every call anyway.
New model: skills declare required env var names; how they are supplied
is up to the agent (own vault, shell env, or ~/.config/k-skill/secrets.env
as the default fallback with 0600 permissions).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The validate job was failing because the KTX helper regression suite imported optional runtime dependencies directly from the module top level. GitHub Actions does not inherit the local user site-packages that made those imports succeed on the workstation, so the test suite died before it could exercise the helper logic.
This change makes the helper import-safe in minimal environments by deferring requests usage, providing lightweight fallbacks for optional Korail/Crypto imports during unit tests, and surfacing an explicit install command when the real runtime dependencies are actually needed. The docs now list pycryptodome alongside korail2, and the regression suite forces PYTHONNOUSERSITE=1 so CI keeps exercising the dependency-light path instead of accidentally relying on a developer machine.
Constraint: PR #19 must keep npm run ci green on GitHub Actions without assuming user-level Python packages
Constraint: The KTX helper still needs the real korail2 and pycryptodome packages for live reservation flows
Rejected: Installing ad-hoc Python packages in the CI workflow | hides the import-safety regression instead of fixing the helper/test contract
Rejected: Removing the Python regression suite from skill-docs coverage | would lose the guard on the train_id reservation flow
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep the KTX helper importable under PYTHONNOUSERSITE=1 and document every required runtime package in both the skill and install docs
Tested: PYTHONNOUSERSITE=1 python3 -m unittest discover -s scripts -p test_ktx_booking.py
Tested: node --test scripts/skill-docs.test.js
Tested: npm run ci
Not-tested: GitHub Actions validate rerun after push
Reserve used to replay search results and trust a fresh ordinal index, which could silently target a different train when sold-out entries disappeared or ordering changed. This change emits a stable train_id from search output, requires reserve to match the exact train identity on replay, and updates docs/tests to lock the safer CLI contract.
Constraint: Korail search results can reorder between search and reserve while the helper still needs to replay the live lookup
Rejected: Keep --train-index as the reserve selector | still allows silent wrong-train bookings when the result set shifts
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: If upstream train identity fields change, update the train_id payload and the docs/tests together before changing reserve selection again
Tested: python3 -m py_compile scripts/ktx_booking.py; python3 -m unittest discover -s scripts -p test_ktx_booking.py; node --test scripts/skill-docs.test.js; npm run ci; live search/reservations/reserve/cancel/reservations with sops-managed Korail credentials
Not-tested: Forced live stale-train_id failure against a disappearing train between search and reserve
The feature branch already restored the patched Korail helper, so this follow-up stays narrow: lock the documented helper flags in regression tests and teach both KTX docs surfaces about the search and waiting-list toggles the live CLI already supports.
Constraint: Follow-up had to stay compatible with the shipped scripts/ktx_booking.py parser and existing PR scope
Rejected: Expand README into a full command matrix | duplicates the dedicated KTX docs and skill guide
Confidence: high
Scope-risk: narrow
Directive: When the helper CLI changes, update both KTX docs surfaces and the regression assertions in the same change
Tested: node --test scripts/skill-docs.test.js
Tested: python3 -m py_compile scripts/ktx_booking.py
Tested: npm run ci
Tested: live python3 scripts/ktx_booking.py search/reservations/reserve/cancel via sops-managed Korail credentials
Not-tested: 예약대기 success path on a sold-out train
Korail's current mobile endpoints reject the published raw korail2
examples with MACRO ERROR, so this change adds a repo-local
helper that patches Dynapath token/Sid/version behavior and reroutes
KTX docs/tests to the helper-based flow.
Constraint: Must keep credentials in sops-managed secrets and prove the flow with a real reservation
Rejected: Fork and publish a patched korail2 package | broader release surface than this repo needs
Confidence: high
Scope-risk: moderate
Directive: Re-check the helper constants and private korail2 hooks whenever Korail changes its mobile anti-bot flow
Tested: python3 -m py_compile scripts/ktx_booking.py
Tested: npm run ci
Tested: Live search via scripts/ktx_booking.py search 서울 부산 20260328 000000 --include-no-seats --include-waiting-list
Tested: Live reserve/cancel via scripts/ktx_booking.py reserve/cancel/reservations on March 28, 2026 KTX #001
Not-tested: Final payment completion after reservation
This snapshots the current repository updates as a coherent release-prep
baseline: workspace/package scaffolding, release automation docs and
workflows, refreshed skill/setup documentation, roadmap expansion, and
the README thumbnail polish.
Constraint: Node packages in this repo must use npm workspaces and Changesets for releases
Constraint: Python release automation stays scaffold-only until a real package exists
Rejected: Split the current work into multiple commits | user asked to commit the current changes together
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Keep release docs, workflows, and package metadata aligned when adding future packages
Tested: npm run ci
Not-tested: GitHub Actions execution on remote after push
The train skills no longer share a generic wrapper. SRT now documents the dedicated SRTrain surface, and KTX now documents korail2 directly, which makes the install path, imports, and reservation examples match the libraries the user explicitly validated.
Constraint: SRT and KTX should stay separate skills with their own native library surfaces
Rejected: Keep the shared koreantrain abstraction | it hides the real backend and weakens trust in the examples
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep future train-skill examples aligned with the concrete upstream library each skill depends on
Tested: bash scripts/validate-skills.sh
Tested: Import and signature inspection for SRTrain and korail2 from temporary installs
Not-tested: Live login and booking against SRT and Korail services
Credential-bearing skills now point to a shared cross-platform setup based on sops plus age instead of a hosted password manager. The repo also gains a default setup skill and a small verification script so users can bring one encrypted secrets file to every relevant skill.
Constraint: The secret workflow must work on macOS, Linux, and Windows without mandatory vendor signup
Rejected: Keep 1Password CLI as the default | it requires account creation and sign-in
Rejected: Plaintext .env as the default | too easy to leak in a repo and too easy for tools to read at rest
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: If a future skill needs stronger isolation than exec-env provides, expose a capability wrapper instead of injecting the raw secret
Tested: bash scripts/validate-skills.sh
Tested: npx --yes skills add . --list
Tested: bash scripts/check-setup.sh (expected failure without sops/age installed)
Not-tested: End-to-end sops encryption and exec-env flow on a machine with sops and age installed
SRT and KTX were the highest-signal v1 skills because existing Python tooling already exposes search and reservation flows. The skills intentionally split search from reservation so the agent can summarize choices before performing side effects.
Constraint: Booking actions are side-effectful and must not run on ambiguous train choices
Rejected: Merge SRT and KTX into one generic train skill | separate entry points are easier to discover and install
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Keep reserve and cancel steps gated on an identified train or reservation target
Tested: bash scripts/validate-skills.sh
Not-tested: Live login and reservation against SRT/Korail services
Jeffrey (Dongkyu) Kim