{"_id":"@afkv/via","_rev":"6-22c10699ca9082a82e6f87af80faa600","name":"@afkv/via","dist-tags":{"latest":"0.3.10"},"versions":{"0.3.5":{"name":"@afkv/via","version":"0.3.5","keywords":["agent","skill","planning","route-map","token-budget"],"author":{"name":"P-to-Q"},"license":"Apache-2.0","_id":"@afkv/via@0.3.5","maintainers":[{"name":"afkv","email":"jydu_seven@outlook.com"}],"homepage":"https://github.com/p-to-q/via#readme","bugs":{"url":"https://github.com/p-to-q/via/issues"},"bin":{"via":"scripts/via.mjs"},"dist":{"shasum":"da91a1527239b4489daef41de6164fffda9750d2","tarball":"https://registry.npmjs.org/@afkv/via/-/via-0.3.5.tgz","fileCount":18,"integrity":"sha512-I/7KLPT7NfihTZgqI3SiVa8fWUVXB1P4G8lqe7UCQY3+Jy44YjRRagGSbX5/FwmDSyIOvj3BXku/yhZIipH/wA==","signatures":[{"sig":"MEUCIQDPTjx6Gcq7uZB7hfWzBsscsok9r4TUzH9GWjcIHJzLQAIgIhaW2K4Vf/VNzO3BQDOEICI49L3u6XuzGHn2kLNv5zE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":90822},"type":"module","engines":{"node":">=20"},"gitHead":"350c32ddc0b99b4d0e206c6b456c02a4edcb5beb","scripts":{"test":"node --test tests/*.test.mjs","check":"npm test && npm run validate:example && npm run build:example && npm pack --dry-run","build:example":"node scripts/via.mjs build examples/web-coder-route.json --out example-output","render:example":"node skills/via-route/scripts/render-route.mjs examples/web-coder-route.json assets/web-coder-route.svg","validate:example":"node skills/via-route/scripts/validate-route.mjs examples/web-coder-route.json"},"_npmUser":{"name":"afkv","email":"jydu_seven@outlook.com"},"repository":{"url":"git+https://github.com/p-to-q/via.git","type":"git"},"_npmVersion":"10.9.3","description":"Turn an engineering task into a Git-tree route map.","directories":{},"_nodeVersion":"22.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/via_0.3.5_1784431431470_0.48488278048523425","host":"s3://npm-registry-packages-npm-production"}},"0.3.6":{"name":"@afkv/via","version":"0.3.6","keywords":["agent","skill","planning","route-map","token-budget"],"author":{"name":"P-to-Q"},"license":"Apache-2.0","_id":"@afkv/via@0.3.6","maintainers":[{"name":"afkv","email":"jydu_seven@outlook.com"}],"homepage":"https://github.com/p-to-q/via#readme","bugs":{"url":"https://github.com/p-to-q/via/issues"},"bin":{"via":"scripts/via.mjs"},"dist":{"shasum":"a90768e1a6ca0d283ae554269eb4fcacee329e72","tarball":"https://registry.npmjs.org/@afkv/via/-/via-0.3.6.tgz","fileCount":18,"integrity":"sha512-nLX5OERGe65hH3cz0I4eCT06e9gUtMInOWiuwzFzcnpGq8/aw/vgHng6WJ6uJuNqRJJoFTdVhg0DJrgFI1vIcw==","signatures":[{"sig":"MEUCIQDCItbFLv05kOw+LfCuXEoUyCv5NRnybqnF0PM7nkHSZQIgeMPMtvl46QMOxr42isk3uNUdqYZj99mLPnwUZzd4+bQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":102970},"type":"module","engines":{"node":">=20"},"gitHead":"885545cbee8a7ec868b8a110c54726c7e6bd718a","scripts":{"test":"node --test tests/*.test.mjs","check":"npm test && npm run validate:example && npm run build:example && npm pack --dry-run","build:example":"node scripts/via.mjs build examples/web-coder-route.json --out example-output","render:example":"node skills/via-route/scripts/render-route.mjs examples/web-coder-route.json assets/web-coder-route.svg","validate:example":"node skills/via-route/scripts/validate-route.mjs examples/web-coder-route.json"},"_npmUser":{"name":"afkv","email":"jydu_seven@outlook.com"},"repository":{"url":"git+https://github.com/p-to-q/via.git","type":"git"},"_npmVersion":"10.9.3","description":"Turn an engineering task into a Git-tree route map.","directories":{},"_nodeVersion":"22.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/via_0.3.6_1784460642686_0.558730963335661","host":"s3://npm-registry-packages-npm-production"}},"0.3.7":{"name":"@afkv/via","version":"0.3.7","keywords":["agent","skill","planning","route-map","token-budget"],"author":{"name":"P-to-Q"},"license":"Apache-2.0","_id":"@afkv/via@0.3.7","maintainers":[{"name":"afkv","email":"jydu_seven@outlook.com"}],"homepage":"https://github.com/p-to-q/via#readme","bugs":{"url":"https://github.com/p-to-q/via/issues"},"bin":{"via":"scripts/via.mjs"},"dist":{"shasum":"263c166f6274d30b24279b8528a7702704e25678","tarball":"https://registry.npmjs.org/@afkv/via/-/via-0.3.7.tgz","fileCount":18,"integrity":"sha512-ogIDhHRDB6nEGGcL+OYN/ESvK7qv09gISsQrt7h9lrKijbn0kk19dhSEOZj3HL+06chtuI/MlfkSp9U3RLHZKA==","signatures":[{"sig":"MEQCICnGvBDQ6t5ZkLQNlZ6nzrMUJ4GnSj/wTsgQ6dU/MP/YAiAVjEyUlnUPipYh3Lyz0cZ8bC4WE6Tl7B07zLUAwfquSw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":112383},"type":"module","engines":{"node":">=20"},"gitHead":"033499117f104b209d978f16ae6c375dcb3e0ac0","scripts":{"test":"node --test tests/*.test.mjs","check":"npm test && npm run validate:example && npm run build:example && npm pack --dry-run","build:example":"node scripts/via.mjs build examples/web-coder-route.json --out example-output","render:example":"node skills/via-route/scripts/render-route.mjs examples/web-coder-route.json assets/web-coder-route.svg","validate:example":"node skills/via-route/scripts/validate-route.mjs examples/web-coder-route.json"},"_npmUser":{"name":"afkv","email":"jydu_seven@outlook.com"},"repository":{"url":"git+https://github.com/p-to-q/via.git","type":"git"},"_npmVersion":"10.9.3","description":"Turn an engineering task into a Git-tree route map.","directories":{},"_nodeVersion":"22.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/via_0.3.7_1784461809963_0.561207550752379","host":"s3://npm-registry-packages-npm-production"}},"0.3.8":{"name":"@afkv/via","version":"0.3.8","keywords":["agent","skill","planning","route-map","token-budget"],"author":{"name":"P-to-Q"},"license":"Apache-2.0","_id":"@afkv/via@0.3.8","maintainers":[{"name":"afkv","email":"jydu_seven@outlook.com"}],"homepage":"https://github.com/p-to-q/via#readme","bugs":{"url":"https://github.com/p-to-q/via/issues"},"bin":{"via":"scripts/via.mjs"},"dist":{"shasum":"0cfc51d03e137fa89fbecf9d611af2b77c171523","tarball":"https://registry.npmjs.org/@afkv/via/-/via-0.3.8.tgz","fileCount":18,"integrity":"sha512-Wzd5bSB2vU90Stg9jIj9ky6G7PfG9GhHlyA06Jq1jPuTxIr78LrsVAe9EwXXQVYzBjppn8eoTpR/rtEcozke2w==","signatures":[{"sig":"MEQCIATbqU3ODvRcJsCLu+RpjGevwRufV8x5X/VbPBRNrKlPAiB5uMJxZJSIUMMT3FS1qp550PfpGUOrMZs0q4S47M/pdA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":115547},"type":"module","engines":{"node":">=20"},"gitHead":"18ce818233ce6f985e9f708846e9f3121ac3a4d0","scripts":{"test":"node --test tests/*.test.mjs","check":"npm test && npm run validate:example && npm run build:example && npm pack --dry-run","build:example":"node scripts/via.mjs build examples/web-coder-route.json --out example-output","render:example":"node skills/via-route/scripts/render-route.mjs examples/web-coder-route.json assets/web-coder-route.svg","validate:example":"node skills/via-route/scripts/validate-route.mjs examples/web-coder-route.json"},"_npmUser":{"name":"afkv","email":"jydu_seven@outlook.com"},"repository":{"url":"git+https://github.com/p-to-q/via.git","type":"git"},"_npmVersion":"10.9.3","description":"Turn an engineering task into a Git-tree route map.","directories":{},"_nodeVersion":"22.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/via_0.3.8_1784462529204_0.47240755434156356","host":"s3://npm-registry-packages-npm-production"}},"0.3.9":{"name":"@afkv/via","version":"0.3.9","keywords":["agent","skill","planning","route-map","token-budget"],"author":{"name":"[p → q]"},"license":"Apache-2.0","_id":"@afkv/via@0.3.9","maintainers":[{"name":"afkv","email":"jydu_seven@outlook.com"}],"homepage":"https://github.com/p-to-q/via#readme","bugs":{"url":"https://github.com/p-to-q/via/issues"},"bin":{"via":"scripts/via.mjs"},"dist":{"shasum":"3c29c40237c23a73680a2c51749c5e70f5152b4e","tarball":"https://registry.npmjs.org/@afkv/via/-/via-0.3.9.tgz","fileCount":18,"integrity":"sha512-Is5qmzSqkVntsoOt4DUc9ZTZ2cPdxYurJHsqiKdMjKxhWV/0bb6p5iHM+9/J6ozrK1gAHeSmLvdqAmeprRksRg==","signatures":[{"sig":"MEQCIARH9qcoUCcXdOWH8FghN0OGcrU8SbWWoTFRRlIjtlDrAiBy3+ESax1JBfP8KzvmRdpMT0yK3MPR1wyuKCVhlNx/sw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":115761},"type":"module","engines":{"node":">=20"},"gitHead":"633faf952c10d405839cfbcea739ffa3a265cc2b","scripts":{"test":"node --test tests/*.test.mjs","check":"npm test && npm run validate:example && npm run build:example && npm pack --dry-run","build:example":"node scripts/via.mjs build examples/web-coder-route.json --out example-output","render:example":"node skills/via-route/scripts/render-route.mjs examples/web-coder-route.json assets/web-coder-route.svg","validate:example":"node skills/via-route/scripts/validate-route.mjs examples/web-coder-route.json"},"_npmUser":{"name":"afkv","email":"jydu_seven@outlook.com"},"repository":{"url":"git+https://github.com/p-to-q/via.git","type":"git"},"_npmVersion":"10.9.3","description":"A Git-tree/Google Map interface for vibe coding decisions.","directories":{},"_nodeVersion":"22.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/via_0.3.9_1784463426658_0.34415134870378483","host":"s3://npm-registry-packages-npm-production"}},"0.3.10":{"name":"@afkv/via","version":"0.3.10","description":"A Git-tree/Google Map interface for vibe coding decisions.","type":"module","engines":{"node":">=20"},"bin":{"via":"scripts/via.mjs"},"scripts":{"render:example":"node skills/via-route/scripts/render-route.mjs examples/web-coder-route.json assets/web-coder-route.svg","validate:example":"node skills/via-route/scripts/validate-route.mjs examples/web-coder-route.json","build:example":"node scripts/via.mjs build examples/web-coder-route.json --out example-output","test":"node --test tests/*.test.mjs","check":"npm test && npm run validate:example && npm run build:example && npm pack --dry-run"},"keywords":["agent","skill","planning","route-map","token-budget"],"homepage":"https://github.com/p-to-q/via#readme","repository":{"type":"git","url":"git+https://github.com/p-to-q/via.git"},"bugs":{"url":"https://github.com/p-to-q/via/issues"},"author":{"name":"[p → q]"},"publishConfig":{"access":"public"},"license":"Apache-2.0","_id":"@afkv/via@0.3.10","gitHead":"270ccf0f31bef37bb655f535ec5b2dd002c1791b","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-kH1jLtKQwGHZ2yMiyFeCiORhspGBHoUmOcbw8tCo1k1ka/ZKPHDFTmgYNKT8NVIqiQzN+dkURKK3clThcajm1w==","shasum":"a3bb2c359f46cf06bb6fb54f5d6788dca4d48436","tarball":"https://registry.npmjs.org/@afkv/via/-/via-0.3.10.tgz","fileCount":19,"unpackedSize":126091,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAGH8StqNMAVZwBJw75/M3rg5OvtUS3rS/qyHfWw+7fDAiAvrttsnRjz6fhl/odhzeecG34hgn3l+pRPxL0GqB680g=="}]},"_npmUser":{"name":"afkv","email":"jydu_seven@outlook.com"},"directories":{},"maintainers":[{"name":"afkv","email":"jydu_seven@outlook.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/via_0.3.10_1785167552734_0.3119821943899721"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-19T03:23:51.273Z","modified":"2026-07-27T15:52:33.086Z","0.3.5":"2026-07-19T03:23:51.596Z","0.3.6":"2026-07-19T11:30:42.832Z","0.3.7":"2026-07-19T11:50:10.163Z","0.3.8":"2026-07-19T12:02:09.395Z","0.3.9":"2026-07-19T12:17:06.866Z","0.3.10":"2026-07-27T15:52:32.921Z"},"bugs":{"url":"https://github.com/p-to-q/via/issues"},"author":{"name":"[p → q]"},"license":"Apache-2.0","homepage":"https://github.com/p-to-q/via#readme","keywords":["agent","skill","planning","route-map","token-budget"],"repository":{"type":"git","url":"git+https://github.com/p-to-q/via.git"},"description":"A Git-tree/Google Map interface for vibe coding decisions.","maintainers":[{"name":"afkv","email":"jydu_seven@outlook.com"}],"readme":"# via\n\n[![CI](https://github.com/p-to-q/via/actions/workflows/ci.yml/badge.svg)](https://github.com/p-to-q/via/actions/workflows/ci.yml)\n[![License](https://img.shields.io/badge/license-Apache--2.0-17181d.svg)](LICENSE)\n\nSee the paths before you build.\n\nvia helps your coding agent reason through the options, then maps 3 potential engineering paths.<br>\nCompare tokens, time, and route summaries at a glance.\n\n```text\nRead https://github.com/p-to-q/via/blob/main/skills/via-route/SKILL.md and follow the instructions to install and configure via.\n```\n\n![via route map](assets/web-coder-route.svg)\n\nThree routes. Real overlap. Local branches. Distinct starts or outcomes when the task calls for them. Token and time ranges.\n\nAt its simplest, via works with a familiar model behavior: after reasoning about an open planning question, models often present three comparable ways forward. That format is broadly legible to users. via keeps the explanations, recommendation, and useful feedback, then adds a picture as another way to understand the same decision. Three remains a natural interface default, never a reason to invent a weak option.\n\nvia keeps the prompt light. It nudges the model to think carefully, understand the user's real intent, and work from the task itself, then leaves the model room to follow its own intuition and native reasoning behavior. RouteSpec constrains the added visual—not the model's thinking interface or written answer—and the bundled scripts handle validation and SVG rendering.\n\nThe product has three reference families. Modern AI-native coding interfaces are one of them: Claude informs on-demand visual artifacts and SVGs. ChatGPT and Codex inform the surrounding UI, coding context, and VI details. Inside via's own interface, Google Maps and Google Earth contribute spatial route comparison, while Git Tree contributes engineering topology.\n\nvia gives this interaction a small engineering fixture: the model puts its routes into RouteSpec and the renderer turns them into the SVG. The schema reduces uncertainty about how to organize the technical structure while the routes, nodes, topology, and recommendation still come from the model's judgment.\n\nOur hypothesis is that this light schema can also help the model think more clearly. Expressing technical work as nodes, dependencies, shared segments, branches, and outcomes may encourage a more principled topology during reasoning. It remains a nudge, not a required reasoning procedure.\n\nvia is designed for the same moment as Plan mode. It gathers the context that matters, asks only consequential questions, and lets the model reason at the depth the task needs before implementation. The difference is the interface: the normal plan and feedback remain, with a route map added beside them. via is an alternative to a text-only planning surface, not a replacement for a host's permissions, reasoning controls, or thinking UI.\n\n## Model fit\n\nvia works best with capable tool-using coding or reasoning models. A practical threshold is a model-agent setup that can inspect a repository, form three materially distinct routes from an ambiguous engineering task, and emit valid RouteSpec with at most one small repair. Smaller models may spend more context following the Skill than they recover from its structure. If the model cannot form distinct routes or reliably produce RouteSpec, use a normal text response instead. See [Model fit and evaluation](docs/model-fit.md).\n\n## Install\n\nvia requires Node.js 20 or newer and has no runtime dependencies.\n\n### Skill entrypoint\n\nvia is loaded through [`skills/via-route/SKILL.md`](skills/via-route/SKILL.md). That file is the Skill entrypoint: it tells the agent when to use via and links to the RouteSpec contract, JSON Schema, evaluator, and renderer scripts.\n\nTo install and configure via inside another coding agent, paste this prompt into that agent:\n\n```text\nRead https://github.com/p-to-q/via/blob/main/skills/via-route/SKILL.md and follow the instructions to install and configure via.\n```\n\nFor Codex, you can also install the Skill from this GitHub repository with the Skill installer:\n\n```text\n$skill-installer install p-to-q/via skills/via-route\n```\n\nThe installer places the Skill under `$CODEX_HOME/skills` and makes it available on the next turn.\n\nYou can also clone the repository and symlink the Skill manually:\n\n```bash\ngit clone https://github.com/p-to-q/via.git\nmkdir -p ~/.agents/skills\nln -s \"$(cd via && pwd)/skills/via-route\" ~/.agents/skills/via-route\n```\n\n### Wake it up\n\nIn a chat box, type `/via` to wake via explicitly:\n\n```text\n/via plan three ways to migrate this auth flow\n```\n\nIn Codex Skill contexts, you can also name the installed Skill directly:\n\n```text\n$via-route plan three ways to migrate this auth flow\n```\n\nAdvanced agents can also trigger via from natural language when the request is clearly route-style planning:\n\n- \"show me three routes for this implementation\"\n- \"make a token map for this task\"\n- \"compare architecture options before we build\"\n- \"plan the migration paths and show the tradeoffs\"\n- \"/via for this decision\"\n\n### Codex Plugin bundle\n\nThe repository contains a validated `.codex-plugin/plugin.json` for plugin packaging and marketplace submission. The first public release is installed as a Skill or CLI; it is not yet published in a Codex marketplace.\n\n### CLI\n\nInstall the CLI from npm:\n\n```bash\nnpm install --global @afkv/via\n```\n\nThe source repository remains [`p-to-q/via`](https://github.com/p-to-q/via). The npm package is published from the maintainer scope while the `@p-to-q` npm organization is being prepared.\n\nOr install directly from GitHub:\n\n```bash\nnpm install --global github:p-to-q/via\n```\n\nCheck the installed version:\n\n```bash\nvia -v\n```\n\nBuild any RouteSpec:\n\n```bash\nvia build route.json --out via-output\n```\n\nValidate without rendering:\n\n```bash\nvia validate route.json\n```\n\nThe output documents itself:\n\n```text\nvia-output/\n├── route.svg\n├── route.json\n└── route.md\n```\n\n## Try the example\n\n```bash\ngit clone https://github.com/p-to-q/via.git\ncd via\nnpm install\nnpm run build:example\n```\n\nOpen `example-output/route.svg`.\n\n## How it works\n\nThe source is one directed graph:\n\n- nodes are engineering checkpoints;\n- edges carry one or more route IDs;\n- shared edges create overlap;\n- branch edges create local detours;\n- routes may share all, some, or none of their path;\n- routes normally share a start and finish, but may declare different origins or outcomes when that is true of the task;\n- `START` and `DONE` are fixed endpoint roles attached to their graph nodes, while their captions are generated from the actual origin and achieved state.\n\nThe Skill creates the RouteSpec, validates it, renders it, and shows the SVG with the model's normal planning response. It skips tiny work and tasks without three credible paths.\n\nThis separation is deliberate: the model decides what the task means, explains the useful paths, and gives its recommendation and feedback; the schema organizes what the additional visual should show; the renderer turns that representation into the interface. via does not ask the model to follow a second reasoning system or compress its useful analysis into the graph.\n\nvia also stays out of the host's thinking UI. If ChatGPT, Codex, Claude, or another agent shows progress or a reasoning summary while it works, that remains available according to the host's own behavior and policy. via governs the added route map, not whether the host exposes a thinking panel or how it labels one.\n\nvia has no persistent mode for the user to manage. It appears when the current turn contains a real route decision. After a route is chosen, the model continues normally from that context. The map is redrawn only when the goal, constraints, evidence, or available paths materially change; once the task becomes straightforward execution, via naturally falls away.\n\nSee the [RouteSpec contract](skills/via-route/references/route-spec.md), [example graph](examples/web-coder-route.json), [product architecture](docs/product-architecture.md), [interface system](docs/design-system.md), [model fit notes](docs/model-fit.md), and [agent surface notes](docs/agent-surfaces.md).\n\n## What via does not claim\n\n- Token ranges compare incremental model workload; time ranges compare active agent time to the next useful engineering deliverable. Both are estimates, not telemetry.\n- via avoids unnecessary prompt and formatting overhead, but it does not shorten useful route explanations merely to save tokens.\n- Three routes are useful only when three materially different paths exist.\n- A structurally valid map does not make its recommendation automatically correct.\n- via is not a mandatory planning workflow. If the map does not save reading time, skip it.\n\n## Research and evaluation\n\nThe bundled [Skill landscape](docs/skill-landscape.md) records the community research behind the design. The repository's [evaluation set](https://github.com/p-to-q/via/tree/main/evals) covers trigger precision, fake-route cases, topology, proof checkpoints, scan speed, and conversation continuation.\n\n## Development\n\n```bash\nnpm install\nnpm run check\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md), [SUPPORT.md](SUPPORT.md), [SECURITY.md](SECURITY.md), [CHANGELOG.md](CHANGELOG.md), and the [0.3.10 release notes](docs/releases/v0.3.10.md).\n\nApache-2.0 © [p → q] contributors.\n","readmeFilename":"README.md"}