pp-iko-yo

Imported from mvanhorn/printing-press-library (cli-skills/pp-iko-yo/SKILL.md). Install upstream with npx skills add mvanhorn/printing-press-library --skill pp-iko-yo. Copyright stays with the author (Apache-2.0).

Iko-yo Trip — Printing Press CLI

Prerequisites: Install the CLI

This skill drives the iko-yo-pp-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows:

   npx -y @mvanhorn/printing-press-library install iko-yo --cli-only

2. Verify: iko-yo-pp-cli --version
3. Ensure the reported install directory is on $PATH for the agent/runtime that will invoke this skill.

If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer). This installs into $GOPATH/bin (default $HOME/go/bin), so add that directory to $PATH instead:

go install github.com/mvanhorn/printing-press-library/library/travel/iko-yo/cmd/iko-yo-pp-cli@latest

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

Discover Iko-yo Trip’s local experiences and municipal events, inspect evidence, and compare a small family shortlist. Keyword and date filters apply only to the reported bounded listing window; cached records retain their observation times. The full core Iko-yo catalog is not integrated.

When to Use This CLI

Use this CLI for selected Iko-yo Trip family spots, municipal events and local experiences across Japan. It is useful when event dates, separate fees, application conditions or explicit family facilities affect a small shortlist. Report the bounded source window and preserve unknown facts.

Anti-triggers

Do not use this CLI for:

• Full core Iko-yo catalog or core age-filter search
• Bookings, payments, reviews, posts or account changes
• Live seat availability or guaranteed age/accessibility suitability

Unique Capabilities

These capabilities aren't available in any other tool for this API.

Find family-trip candidates

• trip discover — Find regional candidates while seeing exactly which listing pages and records were checked.

  Choose this when a trip window matters and complete source coverage is unavailable.

  iko-yo-pp-cli trip discover --kind events --region 6 --prefecture 11 --from 2026-11-14 --to 2026-11-15 --max-pages 2 --agent

Check published conditions

• trip inspect — See published age, indoor, nursing and changing evidence with unknown fields exposed.

  Choose this before deciding whether published family facts meet a requirement.

  iko-yo-pp-cli trip inspect spots/8220 --agent

• trip compare — Compare separate fee statements, payment conditions and explicit application intervals.

  Choose this to compare published costs and deadlines without assuming a total or seat availability.

  iko-yo-pp-cli trip compare spots/8220 events/8412 --on 2026-11-15 --as-of 2026-10-03 --agent

• trip compare — Compare selected outings against age, requested amenities and a trip date using supported, excluded and unknown states.

  Choose this for a small family shortlist that needs explicit constraints.

  iko-yo-pp-cli trip compare spots/8220 events/8412 --on 2026-11-15 --age-months 24 --amenities indoor,nursing,changing --agent

Revisit saved facts

• trip cached — Search saved family facts with their original observation times and collection coverage.

  Choose this to revisit saved records without network access.

  iko-yo-pp-cli trip cached Mooovi --kind spots --agent

Discovery Signals

This CLI was generated with browser-observed traffic context.

• Capture coverage: 0 API entries from 6 total network entries
• Protocols: html_scrape (55% confidence)
• Auth signals: none

Command Reference

events — Operations on events

• iko-yo-pp-cli events get — Inspect published Iko-yo Trip event facts
• iko-yo-pp-cli events list — Fetch structured links from /events
• iko-yo-pp-cli events prefecture — Discover Iko-yo Trip events in a source prefecture
• iko-yo-pp-cli events region — Discover Iko-yo Trip events in a source region

spots — Operations on spots

• iko-yo-pp-cli spots get — Inspect published Iko-yo Trip spot facts
• iko-yo-pp-cli spots list — Fetch structured links from /spots

Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

iko-yo-pp-cli which "<capability in your own words>"

which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 0 means at least one match; exit code 2 means no confident match — fall back to --help or use a narrower query. --json (and other machine formats) keep that exit-2 contract and write {"matches":[]} on stdout so agents can inspect the envelope without treating a miss as success.

Evidence and coverage rules

Use Iko-yo Trip branding when presenting results. This is selected nationwide family experiences and municipal/local events; the full core Iko-yo catalog and its server age/facility filters are excluded.

• Discovery scans at most five pages total across listing kinds, separately from the output limit. Listings are publication-ordered and include archived events. Report coverage, remaining pages, scanned/unknown counts and the zero-result note. An empty bounded scan does not establish that no matching events exist.
• schedule.status distinguishes upcoming and ended records; irregular schedules stay unknown. A published span overlapping a visit date does not establish daily operation or an individual session.
• Compare only explicit age and facility evidence. Missing amenities remain unknown. An indoor area does not imply an entirely indoor venue. Published age descriptions are not formal admission or safety guarantees.
• Preserve separate child/adult fee statements and payment qualifiers. Do not derive a family total, dated quote or available seats. Application intervals, capacities and lottery terms are published evidence only.
• Local facts retain observed_at. Auto inspect/compare tries live first; only a network failure permits saved-detail fallback with a warning. HTTP access errors and rate limits remain errors. Local scans cap records independently of returned matches and cap provenance to 5,000 memberships and 100 collections.
• Saved Trip reads and MCP SQL require a stable, checkpointed cache and use a private snapshot capped at 128 MiB. If active sidecars or changed identity are reported, close writers and retry; do not interpret the error as an empty collection. Live saves use canonical SQLite transactions. Symlinks to singly linked targets work; hard links and %, ? or # in selected/resolved/temp paths are refused. External cache replacement during writing is unsupported. --no-cache skips live snapshot saving.

Recipes

Narrow event candidates

iko-yo-pp-cli trip discover --kind events --region 6 --prefecture 11 --max-pages 1 --agent --select records.ref,records.name,records.schedule,coverage

Inspect published event dates and the exact scanned source window.

Published family facts

iko-yo-pp-cli trip inspect spots/8220 --agent

Read age and facility evidence and unknowns for one source record.

Compare a family shortlist

iko-yo-pp-cli trip compare spots/8220 events/8412 --on 2026-11-15 --as-of 2026-10-03 --age-months 24 --amenities indoor,nursing,changing --agent

Compare constraints, charge qualifiers and application boundaries.

Offline saved facts

iko-yo-pp-cli trip cached Mooovi --kind spots --agent

Search only previously saved normalized records with their provenance.

Auth Setup

The supported Trip pages use ordinary public HTTP and need no account or API key. Source records are published information, not live availability.

Run iko-yo-pp-cli doctor to verify setup.

Agent Mode

Add --agent to any command. Expands to: --json --compact --no-input --no-color.

Global format flags share one contract on source, planning, and --deliver paths:

• --json — one JSON document on stdout

• --compact — keep identity/status/timestamp fields; does not change the document vs stream shape

• --csv / --plain — tabular rows (collection envelopes unwrap to the row array)

• --quiet — one identity value per row, no envelope

• Pipeable — JSON on stdout, errors on stderr

• Filterable — --select keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:

  iko-yo-pp-cli events list --agent

• Previewable — --dry-run shows the request without sending

• Offline-friendly — trip cached and trip inspect --data-source local read selected saved facts

• Non-interactive — never prompts, every input is a flag

• Read-only — do not use this CLI for create, update, delete, publish, comment, upvote, invite, order, send, or other mutating requests

Response envelope

--agent wraps Trip results in a provenance envelope. Ordinary --json returns the bare typed record or collection:

{
  "meta": {"source": "live"},
  "results": <data>
}

For --agent, parse .results and .meta.source. Inspect each record’s data_source and observed_at; comparisons may mix live and saved observations. Coverage belongs to the reported scan only. Human output includes source facts and scan notes; machine formats remain clean.

Paths and state

Agents should treat the CLI's path resolver as part of the runtime contract:

• Use --home <dir> for one invocation, or set IKO_YO_HOME=<dir> to relocate all four path kinds under one root.

• Use per-kind env vars only when a specific kind must diverge: IKO_YO_CONFIG_DIR, IKO_YO_DATA_DIR, IKO_YO_STATE_DIR, IKO_YO_CACHE_DIR.

• Resolution order is per-kind env var, --home, IKO_YO_HOME, XDG (XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME), then platform defaults.

• config contains settings like config.toml and profiles. data contains the selected public-fact data.db; this no-auth integration does not need credentials or cookies. state contains persisted queries, jobs, and teach.log. cache contains regenerable HTTP/cache files.

• Run iko-yo-pp-cli doctor --fail-on warn to surface path warnings. agent-context exposes a schema v4 paths block for agents that need the resolved dirs.

• For MCP, pass relocation through the MCP host config. The MCP binary does not inherit CLI flags:

  {
    "mcpServers": {
      "iko-yo": {
        "command": "iko-yo-pp-mcp",
        "env": {
          "IKO_YO_HOME": "/srv/iko-yo"
        }
      }
    }
  }

Fleet precedence: an inherited per-kind env var overrides an explicit --home for that kind. Use IKO_YO_HOME or per-kind vars as durable fleet levers, and use --home only for a single invocation. Relocation is not reversible by unsetting env vars; move files manually before clearing IKO_YO_HOME, or saved facts and profiles remain under the former root until moved.

Automatic learning

Trip planning inputs are per-invocation constraints. Successful trip invocations disable automatic query learning and journaling. Save and revisit only normalized public source facts through trip inspect, trip discover and trip cached; their original observation times stay visible. Never teach child profiles, contributor identities, private travel histories or personal details. The optional framework learning commands may store only general command patterns after identifiers and personal context are removed. Use --no-learn or IKO_YO_NO_LEARN=true for other commands when needed.

Agent Feedback

When you (or the agent) notice something off about this CLI, record it:

iko-yo-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
iko-yo-pp-cli feedback --stdin < notes.txt
iko-yo-pp-cli feedback list --json --limit 10

Entries are stored locally as feedback.jsonl under the resolved data dir. They are never POSTed unless IKO_YO_FEEDBACK_ENDPOINT is set AND either --send is passed or IKO_YO_FEEDBACK_AUTO_SEND=true. Default behavior is local-only.

Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.

Output Delivery

Every command accepts --deliver <sink>. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:

Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.

Named Profiles

A profile is a saved set of flag values, reused across invocations. Use it when a scheduled or recurring agent reuses the same saved flags while providing different input each run.

iko-yo-pp-cli profile save briefing --json
iko-yo-pp-cli --profile briefing events list
iko-yo-pp-cli profile list --json
iko-yo-pp-cli profile show briefing
iko-yo-pp-cli profile delete briefing --yes

Explicit flags always win over profile values; profile values win over defaults. agent-context lists all available profiles under available_profiles so introspecting agents discover them at runtime.

Exit Codes

Argument Parsing

Parse $ARGUMENTS:

1. Empty, help, or --help → show iko-yo-pp-cli --help output
2. Starts with install → ends with mcp → MCP installation; otherwise → see Prerequisites above
3. Anything else → Direct Use (execute as CLI command with --agent)

MCP Server Installation

1. Install the MCP server:

   go install github.com/mvanhorn/printing-press-library/library/travel/iko-yo/cmd/iko-yo-pp-mcp@latest

2. Register with Claude Code:

   claude mcp add iko-yo-pp-mcp -- iko-yo-pp-mcp

3. Verify: claude mcp list

Direct Use

1. Check if installed: which iko-yo-pp-cli If not found, offer to install (see Prerequisites at the top of this skill).
2. Match the user query to the best command from the Unique Capabilities and Command Reference above.
3. Execute with the --agent flag:

   iko-yo-pp-cli trip inspect spots/8220 --agent

4. If ambiguous, drill into subcommand help: iko-yo-pp-cli trip compare --help.