pp-japan-guide

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

Japan Guide

Public source reads require no account or API key.

Prerequisites: Install the CLI

This skill drives the japan-guide-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 japan-guide --cli-only

2. Verify: japan-guide-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/japan-guide/cmd/japan-guide-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 destinations and attractions, inspect scoped visit facts, and follow source itinerary links. Preserve seasonal qualifiers and source freshness.

When to Use This CLI

Use Japan Guide as a single source for destination and attraction discovery, scoped visit information, short comparisons, and published itinerary labels. Begin with a source directory and reuse returned page IDs. Source IDs and canonical URLs are the lookup keys.

Anti-triggers

Use another tool for bookings, payments, ticket inventory, route calculation, cross-provider rankings or current opening confirmation. Source recommendations are editorial dots, separate from visitor reviews. Schedules and source plans are reference facts.

Unique Capabilities

These capabilities extend the generated source-link foundation.

Planning facts

• guide compare — Compare scoped visit facts for up to five source pages and retain per-item failures.

  Compare a small shortlist using source facts.

  japan-guide-pp-cli guide compare e3001 e3002 --agent

• guide inspect — Keep shrine, museum and garden schedules attached to their own facilities.

  Use facility-specific admission and closure facts.

  japan-guide-pp-cli guide inspect e3002 --agent

• guide inspect — Return source schedules with open_now explicitly unknown.

  Avoid interpreting editorial schedules as live operating status.

  japan-guide-pp-cli guide inspect e3001 --agent

• guide inspect — Read saved compact facts while retaining their original source and retrieval dates.

  Save a source snapshot before an offline planning session.

  japan-guide-pp-cli guide inspect e3001 --cache --agent

• guide destinations — Return a bounded destination page with request, byte and elapsed-time metrics.

  Limit output and inspect single-page source coverage.

  japan-guide-pp-cli guide destinations --region kanto --limit 5 --agent

Command Reference

• guide destinations: one directory; filter by region, name or editorial dots.
• guide interests: source interest labels and canonical topic links.
• guide attractions e2164: one destination; filter exact interest tags or name.
• guide inspect e3002: separate facility hours, closed days, admission, access and dated notices.
• guide compare e3001 e3002: at most five pages; preserve per-item failures.
• guide itineraries: regional source index; --destination e2164 reads local plan links.
• guide itinerary e2400_kanto: bounded source day/stop labels, local visit durations and seasonal closure qualifiers.

Use japan-guide-pp-cli which "temple visit facts" --json and command help for current runtime discovery.

Recipes

Tokyo temples

japan-guide-pp-cli guide attractions e2164 --interest temples --limit 5 --agent --select items

Filter source attraction tags.

Compare facts

japan-guide-pp-cli guide compare e3001 e3002 --agent

Inspect a short list with per-item errors.

Source itinerary

japan-guide-pp-cli guide itineraries --destination e2164 --agent

Return source plans and canonical links.

Auth Setup

Supported public guide pages require no account or API key.

Run japan-guide-pp-cli doctor to verify setup.

Agent Mode

Use --agent for one compact {meta,results} JSON document. Lists default to 10 rows, allow at most 50, and expose scanned_records and next_offset; continue with --offset. Each invocation scans one source page. An empty filtered result carries a coverage note. --select filters the payload before the envelope; --select items makes results a row array.

Cite returned canonical source URLs. Preserve facility identity, source interest tags and destination/event kinds. Hours use JST; yen admissions use JPY. Keep the exact source year on dated facts. open_now: null is explicit uncertainty. Unknown fields remain unknown; facts_truncated directs the agent to the source for omitted text.

event_calendar separates annual recurrence (explicit_year: null) from a dated source notice. Preserve named seating fees and their release-date qualifiers without treating them as current ticket inventory. extraction_limitations discloses unsupported narrative admission layouts. The MCP comparison field accepts space-separated page IDs, bounded to five; raw endpoint mirrors are hidden.

Offline and failures

guide inspect --cache saves only extracted facts. --offline reads them with freshness: offline_snapshot and meta.source: local; retrieved_at and source_updated retain their original meanings. --cache-dir overrides the facts cache. Other guide commands require live source reads.

Inspect's default --data-source auto tries live facts, then an available saved snapshot after an eligible failure. live_failure and a stderr warning explain the local fallback; it retains original timestamps and does not save a new snapshot without --cache. Use --data-source live or --no-cache to disable fallback. A 429 is an error, not a cache fallback. --rate-limit 0 disables pacing; throttle errors exit 7.

A failed explicit snapshot save propagates an error rather than returning older facts after a successful live read. Inspection's MCP tool conservatively permits local writes because it exposes cache; the other six guide tools are read-only. Guide snapshots are separate JSON files, not SQL resources. This CLI has no sync command; use guide commands for source facts and SQL only for the local framework store.

Inspection's machine-format dry-run returns one simulation object (dry_run, action, would) rather than fetched facts, without a source request or snapshot write.

Comparisons return successful items plus non-throttle fetch_failures, with a stderr warning. All-source failure is an error. Rate limits return a typed 429 error and retry guidance rather than empty data. Layout errors and network errors name the source; follow its canonical URL and retry or select another supported source page. --timeout bounds the whole command.

MCP snapshot caching uses the server-owned cache root. The MCP tool rejects caller-supplied cache-dir; direct CLI invocations retain --cache-dir.

Automatic learning

Recall once before discovery; a cold store can be skipped for the session. Treat learning candidates as trials requiring verification. Teach structural queries with identifiers removed. For deterministic calls, add --no-learn or set JAPAN_GUIDE_NO_LEARN=true.

Agent Feedback

Use japan-guide-pp-cli feedback --help for the local feedback format. Record reproducible source-layout or command-contract failures without credentials or personal data.