Pp Wheelog

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/travel/wheelog/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

WheeLog — Printing Press CLI

Prerequisites: Install the CLI

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

2. Verify: wheelog-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/wheelog/cmd/wheelog-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.

Search public WheeLog spots, inspect category-specific equipment questions, and compare a bounded shortlist. Save normalized public-place evidence for offline lookup, recheck triage, straight-line proximity and exact observation changes.

When to Use This CLI

Use WheeLog for public crowdsourced wheelchair-accessibility spot evidence, exact source question comparisons and a small offline public-facility shortlist. Japan is the initial travel use case; source keywords can cover other countries. Preserve report counts, unknowns and source record dates when describing results.

Anti-triggers

Do not use this CLI for:

• Guaranteed accessible routes or personal wheelchair suitability.
• Measured dimensions, live opening conditions or per-report observation dates not supplied by the public source.
• Contributor profiles, personal TrackLogs, messages, posts, bookings or account changes.

Evidence contract

Results retain source IDs, Japanese names, public facility addresses, category question labels, aggregate positive/negative counts and canonical WheeLog URLs. An affirmative report is a contributor report, not a guarantee of accessibility. reported_affirmative, reported_negative, conflicting, unreported, counts_missing, inapplicable, not_checked and unavailable remain distinct. Use categories to choose exact question IDs; a restroom question does not apply to an elevator.

record_created_at and record_updated_at are source record metadata. retrieved_at dates this CLI's observation. Missing update times remain unknown. --from/--to select record dates in the inclusive --timezone calendar window (default Asia/Tokyo); output echoes the UTC request. They do not select individual contributor report dates or trip availability.

Search scans at most five source pages and returns at most 50 records. Detail expansion and comparison are capped at five spots; coverage states how many records were listed, checked or unavailable. --require-question triggers real detail reads and returns an assessment rather than filtering away gaps. Keywords use the source's matching rules; an empty bounded result is not proof that no accessible facility exists.

Saved-only commands read existing evidence without migrations, table creation or permission changes. A missing shortlist is empty. Saved path aliases are resolved to the guarded target; multiply linked database files are rejected. Windows checks file attributes for link counts; unavailable link-count metadata fails closed. A non-empty WAL/rollback journal or a database change during the read returns cache_visibility_unavailable; close other database writers and retry. Auto discovery and inspection try the source first and read saved fallback only after a source failure; a failed cache fallback remains an explicit error. Saved reads use a private snapshot copied from a verified open descriptor (at most 64 MiB); SQL never reopens the selected pathname, and temporary snapshots are removed on completion or error. Refreshing or saving observations still needs a writable database. Source saves, refreshes and removals bind to the same canonical target and verify selected-path identity and a single hard link before opening and around commits on one reserved connection. Writable source-cache paths containing ? or # are rejected before opening; saved-only reads support those names through escaped private-snapshot URIs.

The public contract supplies aggregate equipment answers rather than typed measured widths or slopes, individual report dates, current opening conditions or accessible routes. Read supplementary notes on the canonical source page. Contributor profiles, raw narratives, photos, comments and personal TrackLogs are excluded before cache and output.

auto prefers a fresh source read and labels saved fallback; live requires source requests; local uses saved evidence. shortlist list is always local. categories computes the recorded source catalog and rejects live mode. Save up to 50 selected public spots, retaining only the latest two normalized observations per spot. Retrieval-only differences do not count as source changes. Straight-line distances cover only saved facilities and do not establish a wheelchair route; the supplied origin is not stored.

Unique Capabilities

These workflows combine verified public spot evidence with a bounded saved shortlist.

Recorded evidence

• spots compare — Align requested source question IDs and report supporting, opposing, mixed, unknown and inapplicable evidence.

  Choose this when comparing an explicit shortlist against source question evidence.

  wheelog-pp-cli spots compare 166345 166344 --require-question 102 --agent

• spots search — Expand a bounded keyword shortlist into actual detail evidence for requested questions.

  Choose this when candidate search results need actual question counts before triage.

  wheelog-pp-cli spots search 成田空港 --category toilet --require-question 102 --limit 3 --agent

Saved shortlist

• shortlist changes — Show exact changes between two allowlisted source observations for selected public places.

  Choose this to inspect source evidence changes without asserting physical changes.

  wheelog-pp-cli shortlist changes --data-source local --agent

• shortlist list — Prioritize old, unknown or conflicting evidence in a saved shortlist with explicit reasons.

  Choose this for saved-list maintenance and missing or conflicting question evidence.

  wheelog-pp-cli shortlist list --audit --require-question 102 --max-record-age 180d --agent

• shortlist list — Rank saved public facilities by straight-line distance from an explicit origin.

  Choose this for offline proximity within the saved shortlist, with no route promise.

  wheelog-pp-cli shortlist list --origin 35.7742,140.3879 --radius-m 500 --category toilet --agent

Discovery Signals

The public web application's anonymous search and detail requests were observed on 2026-10-03 and replayed over ordinary HTTPS. The supported source surface is POST-based read-only RPC with an explicit semantic success envelope. It requires no credentials, cookies or browser runtime. The CLI allowlists public-place fields before storage or output and stops with a contract error if the source envelope changes.

Command Reference

spots — Public crowdsourced facility accessibility evidence

• wheelog-pp-cli spots inspect — Inspect allowlisted public accessibility question reports for a source spot ID.
• wheelog-pp-cli spots search — Search public spot records by source keyword, category, and evidence record dates.
• wheelog-pp-cli spots compare — Compare up to five selected IDs against exact source question IDs.
• wheelog-pp-cli categories — List exact category values and question-ID ranges.
• wheelog-pp-cli shortlist save <id...> — Save normalized public facility observations locally; no contributor or account writes.
• wheelog-pp-cli shortlist list — Read saved evidence, --audit recheck reasons or --origin straight-line distances.
• wheelog-pp-cli shortlist changes — Refresh a bounded selected set or compare its last saved transition with --data-source local.
• wheelog-pp-cli shortlist remove <id> — Remove local saved membership and evidence.

Finding the right command

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

wheelog-pp-cli which "recorded toilet equipment"

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.

Recipes

Dated restroom records

wheelog-pp-cli spots search 成田空港 --category toilet --from 2026-10-02 --to 2026-10-02 --timezone Asia/Tokyo --limit 3 --agent

Request the explicit Japanese record-date window; output echoes the UTC backend interval.

Requested equipment comparison

wheelog-pp-cli spots compare 166345 166344 --require-question 102 --agent

Keep inapplicable, unreported, conflicting and unavailable evidence distinct.

Small inspection output

wheelog-pp-cli spots inspect 166345 --agent --select id,name,questions

Return only selected public spot and question facts.

Offline shortlist rechecks

wheelog-pp-cli shortlist list --audit --require-question 102 --data-source local --agent

Prioritize local evidence gaps without network requests.

Auth Setup

The supported public spot surface works anonymously over ordinary HTTPS. No account, API key, cookies or resident browser is needed.

Run wheelog-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 promoted, novel, sync, and --deliver paths:

• --json — one JSON document on stdout (sync progress events go to stderr)

• --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:

  wheelog-pp-cli spots search 成田空港 --agent --select results.id,results.name,coverage

• Previewable — --dry-run summarizes the intended action without executing the command

• Non-interactive — never prompts; inputs use flags or positional arguments

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

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 WHEELOG_HOME=<dir> to relocate all four path kinds under one root.

• Use per-kind env vars only when a specific kind must diverge: WHEELOG_CONFIG_DIR, WHEELOG_DATA_DIR, WHEELOG_STATE_DIR, WHEELOG_CACHE_DIR.

• Resolution order is per-kind env var, --home, WHEELOG_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 data.db with saved public-facility evidence and optional learning rows. state contains invocation state and teach.log. cache contains regenerable HTTP/cache files.

• Run wheelog-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": {
      "wheelog": {
        "command": "wheelog-pp-mcp",
        "env": {
          "WHEELOG_HOME": "/srv/wheelog"
        }
      }
    }
  }

Fleet precedence: an inherited per-kind env var overrides an explicit --home for that kind. Use WHEELOG_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 WHEELOG_HOME, or doctor will not find saved evidence or state left under the former root.

Automatic learning

This CLI ships a self-capturing learning loop. The CLI does its own bookkeeping: every invocation is journaled locally, a failed flag followed by a corrected retry auto-derives a flag_alias candidate, and a teach on a query family without a playbook auto-synthesizes a playbook_candidate from the session's journal. Your job is judgment only: recall first, act on surfaced candidates, teach the final answer, playbook amend when you observe a correction. You never record failures by hand.

Step 1: recall before any discovery

Before list/search/drill commands on a new user question, pass the question as an argv or MCP tool argument to recall --agent. Do not interpolate user-controlled text into a shell command line.

Quoted recall "<question>" breaks on an apostrophe, which is ordinary English. A quoted heredoc breaks when a body line equals the delimiter, and that delimiter is published in these docs. Write the question with a non-shell file-writing tool, then read it back as data:

# Write the question verbatim with your file-writing tool (no shell involved).
# Command substitution on a file only ever yields data — the shell never
# parses the file's bytes as syntax.
QUERY=$(cat /tmp/wheelog-question.txt)
wheelog-pp-cli recall "$QUERY" --agent

Prefer MCP: pass the question as the tool's query argument. "$QUERY" after a file read is argv-safe; putting the question itself in the command text is not.

The response envelope:

{
  "query": "...",
  "normalized": "<normalized form>",
  "query_entities": ["..."],
  "found": true | false,
  "match_score": 0.0,
  "results": [
    { "resource_id": "...", "resource_type": "...", "venue": "...",
      "confidence": 2, "entity_match": "exact|partial|unknown",
      "source": "taught|preseed|pattern", "warnings": ["..."] }
  ],
  "mismatches": [ /* only when --debug-mismatches */ ],
  "warnings": [ /* top-level */ ],
  "candidates": [
    { "id": 12, "class": "flag_alias | playbook_candidate",
      "summary": "...", "sightings": 3, "last_seen": "...",
      "rationale": "...",
      "next_action": ["<trial command>", "wheelog-pp-cli learnings confirm 12"] }
  ],
  "playbook": {
    "query_family": "...",
    "playbook": {
      "steps": [ { "cmd": "<command with {slot} substitution>", "purpose": "..." } ],
      "entity_slots": ["$ENTITY"],
      "expected_tool_calls": 3
    },
    "slots_resolved": { "$ENTITY": { "token": "<live token>", "canonical": "<canonical>" } },
    "notes": "<workarounds + gotchas for this query family>"
  },
  "notes": "<duplicate surface for non-playbook callers>"
}

Empty-store short-circuit: if the store has no learnings, playbooks, or candidates yet (recall finds nothing and learnings list and learnings candidates are both empty), skip recall for the rest of this session instead of taxing every query; resume recall-first once something has been taught.

Step 2: decision tree

Read candidates, playbook, notes, results[0], and warnings in that order:

if Candidates present (warnings include "candidates_present"):
    -> candidates are try-then-confirm, never facts. Follow each candidate's
       two-step next_action verbatim: run the trial command first, then run
       `learnings confirm <id>` only after the trial verified the behavior.
       Reject a wrong candidate with `learnings reject <id>`.
    -> NEVER re-teach something recall surfaced as a candidate; confirm or
       reject that candidate instead of teaching a duplicate.
    -> candidates ride alongside playbooks and resource hits, not instead of
       them; continue with the branches below after acting on them.

if Playbook present:
    -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose)
    -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries
       for the entity slot tokens. If a step's slot is unresolved, fall back to
       discovery for that step only.
    -> the Playbook's expected_tool_calls is a budget; if you find yourself running
       materially more, record the divergence via `wheelog-pp-cli playbook amend`
       at end-of-session.

elif Notes present (no Playbook):
    -> read Notes verbatim before any discovery step; they carry known gotchas
       for this query family even when no structured choreography exists yet.

elif Found AND Results[0].EntityMatch == "exact" AND Results[0].Confidence >= 2:
    -> skip discovery; fetch live data for Results[*].ResourceID in parallel

elif Found AND Results[0].EntityMatch == "partial":
    -> candidate hint, NOT a hit; read the resource title to validate before trusting

elif (any row in Mismatches[] when --debug-mismatches was passed):
    -> treat as cold start; the stored learning is for a different entity
       (different canonical resolved from query_entities)

else:  // Found == false, no playbook, no notes
    -> cold start; run discovery normally; teach the answer afterward (Step 4).
       If the family has no playbook yet, that teach auto-synthesizes a
       playbook candidate from this session's journal - you do not need to
       record one by hand.

Playbook and Notes are orthogonal to the per-resource path. A recall response can carry both a Playbook AND a Results[] hit - use both: the Playbook tells you which choreography to run; the resource hits short-circuit specific steps. Default to skipping mismatches; pass --debug-mismatches only when investigating cold-start surprises.

Candidate judgment details: learnings confirm <id> prints the candidate's full payload before materializing it - check that the printed payload matches the behavior you verified. learnings reject <id> tombstones the derivation signature so the same candidate does not resurface. The envelope carries only the few candidates worth acting on now; wheelog-pp-cli learnings candidates lists the full open set.

Graceful degradation: if learnings confirm is an unknown command, you are driving an older binary - ignore the candidates guidance and follow the rest of the protocol.