viafrei 1.3.15 → 1.3.16

package/CHANGELOG.md

@@ -3,6 +3,380 @@
 All notable changes to this package are documented here. The format follows Keep
 a Changelog and the versions follow Semantic Versioning.
 
+## [Unreleased]
+
+Nothing yet.
+
+## [1.3.16] - 2026-09-27
+
+**This is the release that delivers the licence corrections to the people the
+licences point at.** `NOTICE` is the file Apache-2.0 § 4(d) makes every downstream
+redistributor carry, and until this publish the corrected text existed only in the
+repository: the 1.3.15 tarball on the registry still carries the previous wording. So
+publishing is not a side effect of the correction, it **is** the correction — which
+is the whole reason this release exists, because nothing in `dist/` changes.
+
+The number matches the running service rather than counting the changes here.
+Production answered `initialize` with `1.3.16` when it was asked on 2026-09-27, and
+this package is the bridge to that server, so somebody comparing the two now reads
+one number instead of wondering which is behind.
+
+**No behaviour changes.** `dist/` is built rather than committed, and no file under
+`src/` has changed since the 1.3.15 tag — which is the evidence for the claim, since
+a diff of an untracked directory would be no evidence at all. So no flag, default or
+exit code moves. **Six** of the seven `files` entries do change —
+`README.md`, `LICENSE`, `NOTICE`, `SOURCES.md`, `CHANGELOG.md` and the new
+`API.md` — and the tarball goes from twenty paths to twenty-one. (Six *entries*,
+not six files: `dist` is a directory.)
+
+This paragraph has now been wrong twice, which is worth leaving on the record
+rather than tidying away. The first draft called these "the repository's own
+development scripts" and said the next tarball would differ in two files — true of
+the first change here, false once the licence work landed beside it. The second
+draft said **four** files and omitted `LICENSE` — and the commit that wrote that
+sentence is the same commit that changed `LICENSE`, so it was false at the moment
+it was written, in the paragraph written to correct a false count. The count moved
+once more at the cut, because `API.md` joined `files` in this release. Every
+version of it has been computed from `package.json`'s `files` intersected with
+`git diff --name-only v1.3.15..HEAD`, with the path count from `npm pack --json`,
+rather than counted by eye — which is the only way this sentence has ever been
+right.
+
+### Added
+
+- **A sweep that keeps the twenty-first call site from being written by accident**
+  (`scripts/tools.test.mjs`, `npm run test:tools`, and a step in CI). Eighteen
+  cases: what `resolveTool` accepts and refuses, that its directory list is
+  root-owned and not group- or other-writable (the property the module relies on,
+  rather than the list that is supposed to have it), that its contents cannot be
+  extended at runtime, that an `npm_execpath` which is absolute, real and readable
+  but not npm is refused, and then a sweep of all thirty-two source files,
+  walked recursively, for a spawn whose program is a bare quoted name.
+
+  It carries three preconditions, because a gate whose input is absent reports
+  success about what it never read: **every** source root must have contributed a
+  file and an unreadable root is a failure rather than an absence; the expression
+  must locate a program argument in a real file of this repository, proved by
+  putting a real call's program back to a literal in memory and requiring it to be
+  found; and it must go red on a planted bad call, with the fixtures assembled at
+  runtime so no literal in this file can satisfy its own sweep.
+
+  Both of the last two exist because the first drafts did not do what their own
+  comments claimed. The floor was a floor on the *sum*, and `scripts` and `test`
+  clear it between them — so `src/` could be deleted entirely and the run still
+  printed ok at 21 files. And the "it can see a call" precondition evaluated the
+  real expression only on the negative case; the positive half used a different,
+  simpler pattern and never asked the real one to read a file.
+
+  Proved the way a gate has to be: one real call site reverted to a bare name
+  turns the sweep red, one source root removed turns precondition 1 red, and the
+  files were restored byte-identical afterwards.
+
+- **[API.md](API.md): a reference for all 18 tools, generated rather than written.**
+  `catalogue.json` is what the production server answered when it was asked to
+  describe itself — `initialize` plus `tools/list`, `resources/list`,
+  `resources/templates/list` and `prompts/list`, captured on 2026-09-27 from
+  server `1.3.16`. `scripts/gen-api-doc.mjs` renders the document from it
+  (`npm run docs:api`), and `npm run check:docs` in CI fails if the two have
+  drifted. Every tool description in it is the server's own text, verbatim,
+  because that text is what an assistant reads when it decides which tool to
+  call — paraphrasing it would document a different server.
+
+  **No tool was invoked to produce the snapshot.** Listing is metadata; calling is
+  traffic, and one of the providers behind this service sets a floor on how often a
+  station may be queried, with the access itself at risk if it is exceeded. The
+  capture is therefore five list methods and nothing else.
+
+  **What generating it does and does not fix**, because README.md already argued
+  the opposite case and that argument was right. Drift between the document and the
+  snapshot is now impossible to keep — CI regenerates and compares. Drift between
+  the snapshot and the live server is not fixed by anything, because a capture is a
+  point in time. So API.md's own header says it is a dated snapshot, carries the
+  date, and names the running server as the source of truth — in that file and not
+  only in README.md. Both of them ship in the tarball, so that is not the reason;
+  the reason is that a qualification has to travel with the document it qualifies,
+  because somebody who opens the catalogue to look up a parameter has no occasion
+  to read the page beside it.
+
+  Two substitutions in the snapshot, both recorded in its own `$comment` rather
+  than left as silent differences from what the server sent: the 18 per-tool
+  `$schema` declarations are dropped as one constant repeated 18 times, and two
+  288-character date patterns are stored as their LENGTH. The second was forced by
+  the leak sweep and the interesting part is which side gave way — such a regex
+  spells its arithmetic as character classes of selected digits, which a digit-run
+  scanner cannot tell from a five-digit internal value. Both remedies on the
+  sweep's side would have been falsehoods: narrowing the scanner weakens it for
+  every file, and an allow-list entry would record that a character class is a
+  number this project publishes. So the text that cannot be scanned is not stored.
+  Nothing is hidden by it — the document already summarised a pattern over 60
+  characters by its length, and the server hands anyone the full expression.
+
+  One parameter is an object whose seven keys each carry their own bounds, and the
+  first draft rendered it as a dash in both the default and the constraints
+  column — the table's strongest claim broken on the row with the most to say. The
+  cause defeated the safety net as well: `properties` sat in the set of keywords
+  the renderer treats as handled, so the fallback that lists an unrecognised
+  keyword as a bare name never fired. The keyword was known; it was simply never
+  rendered.
+
+- **A self-test for the API-reference generator** (`scripts/gen-api-doc.test.mjs`,
+  `npm run test:docs`, and a step in CI). Its cases include the drift check refusing a
+  hand-edited file, never writing during `--check`, and naming `docs:api` when the
+  document is absent; eight snapshot mutations each refused with a named reason; a
+  malformed `required` rendering rather than throwing; a planted nested `default`
+  reaching the document; a union type in a table cell and in a bullet; an
+  array-of-scalar; and the reported line count agreeing with `wc -l`. The run prints
+  the total, which is the number to trust — this file has been wrong about counts
+  more than once, so it states none here.
+
+  It exists because the generator was the only script here making claims with nothing
+  checking them, and the same six mutants were being re-run by hand across three
+  review rounds — a check performed by remembering is not a check. It also earned
+  itself immediately, by catching two defects nothing else could:
+
+  The whitespace-flattening expression, rewritten to remove a super-linear
+  backtracking pattern, **was not equivalent to what it replaced.** It handled only
+  spaces and tabs beside the newline, so a `\r\n` line ending would have left a stray
+  carriage return in the document. API.md regenerated byte-identical, `--check`
+  passed, every gate was green — because this snapshot contains no CRLF. An output
+  comparison can only speak about the input it was given, so the test compares the two
+  **expressions** over every string up to length four drawn from a whitespace-heavy
+  alphabet, plus random longer ones, and asserts first that the alphabet can expose
+  the bug that shipped.
+
+  And a **union type was escaped twice**: `typeOf` joined with an already-escaped pipe
+  and the cell renderer escaped that pipe again, giving `string \\| null` — a literal
+  backslash, and a bare pipe left to end the table row early. In a bullet, which is not
+  a table, it produced a stray backslash instead. No tool in this snapshot declares a
+  union type, so neither was reachable and no comparison of documents could have found
+  it. Escaping now happens in one place, the one that knows it is writing a table cell.
+
+- **[SUPPORT.md](SUPPORT.md)**, so GitHub's issue chooser has somewhere to point:
+  where a question, a wrong answer and a security report each go, and what makes a
+  report actionable.
+
+- **README gains a Documentation table and five worked use cases** — a motorway
+  briefing, a broken commute including a station lift that is out, an EV weekend, a
+  dispatcher's morning brief, and a local-guide agent — each named by the question
+  it answers rather than by the tools it calls.
+
+### Changed
+
+- **One entry of 13 characters left the leak sweep's private-name list, under that
+  list's own rule 1.** The rule is stated in `scripts/rules.json`: an entry must not
+  be a substring of text this repository legitimately prints, because such an entry
+  can never be satisfied, and the only ways out are deleting it or narrowing the
+  scanner — which is strictly worse. There is no mechanical test for it; the sweep
+  going red *is* the test, and it went red. Declared narrowing: one spelling of 13
+  characters is no longer matched anywhere. The list's second rule is not engaged,
+  which decides that nothing else follows: the audit recorded in that file says
+  nothing on the list is from the class whose harm is confirming a guess —
+  credentials, tokens, session or contract identifiers, access-granting hostnames,
+  personal data — so there is no rotation and no rename here.
+
+  Recorded that way on purpose, and it is a change of practice rather than of
+  style. The two removals recorded under 0.0.9 described what the entries were
+  ABOUT, and taken together those descriptions narrowed the candidate space for a
+  live entry further than a hash does — the same caption failure the number
+  allow-list refuses on the facing page. The file now ends with the ruling: record
+  the rule, the lengths and the narrowing, never the subject. This is the first
+  entry written under it. The older wordings stay where they are, because editing
+  a published file does not unpublish it.
+
+  Coverage was asked of the change rather than asserted, since going from six
+  entries to five must not leave the sweep reporting PASS about what it no longer
+  looks for. The matcher was exercised per slot without needing any real name:
+  the list replaced by five planted names, each planted in text, five reds
+  required, and a negative control that stays clean. The sweep also prints the
+  list's size on every run, so the change is visible rather than silent, and the
+  gate self-test still refuses an emptied list. The window `minTokenLength` and
+  `maxTokenLength` is unchanged at 7 and 15: both are stored literals, neither is
+  derived from the list, and the removed entry sat at neither bound, so no
+  published number narrowed.
+
+- **`numbers.allowed` admits four values the SERVER publishes about itself** — two
+  inside tool descriptions and two as bounds in its own input schemas — under one
+  general rule written into that file rather than a caption each, because a caption
+  per value is the construction the list exists to avoid. It is safe to state in
+  general terms because the sweep already refuses an allowed number that occurs
+  nowhere in the tree, so an exemption cannot outlive its reason.
+
+- **Four statements about other people's licences were wrong, and they are the kind
+  a reader acts on.** Every one was verified against its own source before it was
+  changed, and each correction says that an earlier version had it wrong rather than
+  quietly reading better.
+  - **Share-alike reaches adaptations, not aggregations.** `SOURCES.md`, `NOTICE`
+    and `README.md` all said DELFI data must not be blended into a result under a
+    different licence. CC BY-SA 4.0 art. 3(b) is expressed only over Adapted
+    Material (art. 1(a)); showing licensed data beside another source's data is an
+    aggregation, and Creative Commons states in terms that the condition "applies
+    only for works considered adaptations under copyright law, not simply in
+    collections with other works". Worse than generous in two ways: art. 3(b)(3)
+    forbids imposing terms that restrict rights the licence grants, which is what
+    telling you an aggregation is forbidden does — and the rule as written condemned
+    this service, since a weather answer can name `["dwd","osm"]`.
+  - **The DELFI licence version was sourced to nothing.** Measured at both levels
+    on 2026-09-27: the GovData record for the realtime feed carries the unversioned
+    licence URI and an empty dataset-level licence, and the national access point's
+    own metadata reports the same unversioned term. The publisher's sibling feeds in
+    the same catalogue *are* versioned, so it states a version when it means one.
+    The page now names the family, shows the evidence, and says to treat the
+    share-alike as applying regardless — because the version decides what a
+    recipient may put on a derivative (art. 3(b)(1)), and 3.0 unported has no
+    express database-rights clause where 4.0 art. 4 does.
+  - **§ 7 DWD-Gesetz prescribes a duty, not a wording.** Fetched verbatim: the
+    section is headed *Quellenschutz*, requires distribution to be "nur unter
+    Angabe der Quelle zulässig" and sets no text — and its second sentence adds
+    that fuller protection under the Urheberrechtsgesetz "bleibt davon unberührt",
+    so attribution is the statute's minimum rather than the whole of what may be
+    owed. The three words come from the DWD's own guidance, which also permits the
+    logo form — so a reader told the statute fixes the characters might refuse a
+    form the publisher expressly allows.
+  - **`NOTICE` understated the ODbL duty, and it is the file that republishes
+    itself** (Apache-2.0 § 4(d) makes every downstream redistributor carry it). It
+    said "address results" where the predicate is which *table* answered — place
+    resolution falls through the gazetteer to the OSM tables, so any answer about a
+    place may be OSM-derived — and offered one extract where the § 4.6 offer covers
+    both addresses and points of interest.
+
+### Fixed
+
+- **Every external program these scripts run is now resolved to an absolute path
+  instead of being looked up on `$PATH`** (`scripts/tools.mjs`). `git`, `tar`,
+  `npm` and a `mkdir` were spawned by bare name, which means the environment — not
+  this repository — decided which program actually ran. That matters more here
+  than it would elsewhere: one of these scripts is the leak sweep that decides
+  whether a commit may be published, and another is the hygiene gate that reads
+  the tarball about to be uploaded to the registry. A gate whose implementation
+  the caller can substitute is not a gate. SonarCloud reported seven of the call
+  sites as `javascript:S4036` and the project's Security Rating on new code stood
+  at B because of them.
+  - `git` and `tar` now come from `/usr/bin` or `/bin` only. `/usr/local/bin` and
+    `/opt/homebrew/bin` are deliberately not searched: they are writable by the
+    logged-in user on a normal developer machine, so admitting them would
+    reinstate the substitution this change removes. A tool that is genuinely
+    elsewhere makes the scripts refuse and say where they looked, which is a
+    better failure than quietly running something else.
+  - `npm` is no longer treated as a program at all. It is a JavaScript file, so it
+    is run as `<absolute node> <absolute npm-cli.js>`; node's own path is
+    `process.execPath`, which nothing can substitute. `mkdir` was replaced by
+    `fs.mkdirSync` — no subprocess at all.
+  - **Twenty call sites changed, not the seven that were reported.** The other
+    thirteen are in the two self-tests, which SonarCloud does not analyse. Leaving
+    them would have left the rule true of the code and false of the repository,
+    and a rule with a quiet exemption is the one nobody remembers when adding the
+    next call. (Counted per file in the finished tree: `check-leaks.mjs` 2,
+    `check-tarball.mjs` 4, `npm-pack-json.mjs` 1 — Sonar's seven — then
+    `check-leaks.test.mjs` 3 and `check-tarball.test.mjs` 10. The first version of
+    this entry said nineteen, because it was counted with a single-line grep that
+    cannot see the one call whose program argument sits on its own line. A count
+    taken with the wrong instrument, in a release whose own subject is exactly
+    that.)
+
+- **And the repair for that duplicated it, which the quality gate caught before
+  the merge.** The precondition was *copied* from one self-test into the other —
+  eleven lines — and SonarCloud failed the pull request on **3.1% duplication on
+  new code** against a 3% limit, over exactly that block. Copying was the wrong
+  half of the right idea: the answer was always one implementation used twice.
+  It now lives in `scripts/fixture-root.mjs` as `missingFixtureImports()`, and each
+  self-test keeps its own refusal wording, because the two name different builders
+  and exit by different routes — a difference that is real rather than incidental.
+  Re-proved in each: dropping `tools.mjs` from a caller's file list makes that file
+  refuse by name, and each names its own builder.
+
+  **Concentrating the guarantee doubled its blast radius, so it got the assertion
+  it never had.** One function now stands behind every self-test that uses it, so a
+  silent `return []` disarms all of them at once and restores the wrong-reason pass
+  that started this thread — a sweep that cannot start, reporting no findings. The
+  number of those callers is deliberately not written here or in the module: it grew
+  again inside this release, and the sentence that said "both" went stale unnoticed
+  in five places while the corrected wording lived in one. On an ordinary run they
+  only ever exercise the complete-fixture path, so
+  until now the "missing" branch was proved solely by hand-mutating a file list:
+  four times by two people, and never again by anything. Two cases cover both
+  directions on a temporary directory, and they are mutation-proved — a planted
+  `return []` reddens one, and ignoring the directory argument reddens both.
+
+  Worth recording as the shape rather than the incident. A missing precondition was
+  fixed by adding one; adding it introduced a duplicate of it; the gate caught the
+  duplicate. Three links, and every one of them was found by something other than
+  the test suite, which was green at each step. The file count in this entry moved
+  from twenty-eight to twenty-nine because of it, then to thirty when this release
+  added a source file of its own, and then to **thirty-two** as it added the generator's
+  self-test and the module they share. The first two were re-derived from `npm run test:tools` rather than
+  incremented by hand. The third was not, and the review round found it stale. The
+  fourth was not typed either: it was read out of `npm run test:tools`'s own output
+  and the edit refused to write a number the command did not report. That was a
+  one-off script in a scratchpad, not something this repository carries — said plainly
+  because an earlier draft of this very sentence claimed a committed artefact that
+  does not exist. This paragraph has been wrong before, and that was the first time
+  it invented an artefact rather than a number.
+
+- **The leak sweep's own self-test had no precondition on the fixture it builds,
+  and reported a scope regression instead.** Both self-tests copy a named list of
+  files into a throwaway repository, and `tools.mjs` was missing from both lists.
+  `check-tarball.test.mjs` refused by name, which is what a precondition is for.
+  `check-leaks.test.mjs` had no such check: **measured**, three of its four cases
+  failed with messages about scope — "expected a clean exit, got 1", "the run does
+  not say which scope it used" — because every invocation died of
+  `ERR_MODULE_NOT_FOUND`, and the fourth case *passed*, since a sweep that cannot
+  start also cannot report a finding. That is worse than a red suite: it sends the
+  next reader after the ruleset instead of after a missing file. It now refuses by
+  name, proved by dropping the file again.
+
+- **`npm_execpath` was trusted if it was merely absolute and ended in `.js`** —
+  which reversed this change's own thesis for npm. The decider had moved from
+  `$PATH` to an environment variable, and the local review demonstrated it by
+  pointing the variable at a hand-written file, which the tarball gate would then
+  have run as npm. The value must now also be *shaped* like npm's CLI, ending in
+  `node_modules/npm/bin/npm-cli.js`. What that does not claim, because a security
+  note that overstates its reach is worse than none: anyone who can both set your
+  environment and create a file at that path is still obeyed — and anyone able to
+  do both can usually substitute node itself. The narrowing is from "any writable
+  path" to "a path that looks like a real npm installation": **it stops accidents,
+  not an attacker**, and it is not a privilege barrier. An earlier draft said
+  "stray, mistaken or opportunistic", which the sentence after it contradicted — an
+  opportunistic value costs one `mkdir -p`.
+
+- **`npmCliPath()` refused to find npm on a Homebrew Mac.** Its first draft knew
+  only the `../lib/node_modules/…` layout, which is what the GitHub-hosted runner
+  and nvm use — so it passed in CI and failed on a developer's machine, where
+  Homebrew puts npm under `../libexec/lib/node_modules/…`. Both layouts are tried
+  now, each from the given path and again through `realpathSync`, since a node
+  reached by a symlink resolves its siblings from the real location. Caught by the
+  new self-test on the first run, which is the argument for having written it.
+
+- **The false-positive fix opened a worse false negative, and the second review
+  round caught it.** Excluding `RE.exec('git')` by putting a `(?<!\.)` lookbehind
+  in front of the whole alternation also excluded every *member-expression* spawn —
+  `child_process.execFileSync('git', …)`, `cp.execSync('git status')` — which is a
+  shape SonarJS does report and a contributor can write without doing anything
+  unusual. So a fix aimed at a shape nothing writes blinded the sweep to a shape
+  people do. The lookbehind now applies to the bare name `exec` alone, measured
+  over twelve shapes: the all-names form was wrong on four of them, this one on
+  none. The one trade it still makes — `obj.exec('git')`, a method named `exec` on
+  something that is not a regular expression — is in the limits list, because no
+  expression can tell it from `RE.exec('git')` without a parser. Both directions
+  are pinned in the preconditions now rather than left incidental, since a review
+  round changed this behaviour by accident once already.
+
+  Two smaller things fell out of it. The comment describing the lookbehind said
+  `(?!\.)` where the code says `(?<!\.)` — a look*ahead* there would match nothing
+  useful, so it was the one comment in the file that would mislead somebody
+  "fixing" the code to match it. And the worked examples added to document the
+  twelve shapes turned the file red, because an example of a bare call, spelled as
+  one, *is* a bare call as far as the sweep is concerned; they carry no quote
+  characters now. The sweep catching its own documentation is the least ambiguous
+  evidence available that the member-expression form works.
+
+- **Two documents that enumerate the gates had gone stale in the same commit that
+  added one.** `CONTRIBUTING.md` said "four more checks exist, and CI runs all
+  four" — five now, and the new one was missing from the block a contributor is
+  sent to, which also made the next paragraph's "a fifth command" read as a
+  contradiction. The pull-request checklist named two gates as "the
+  public-repository gates", so a contributor following it would not have run the
+  sweep that exists to catch exactly the call they might be adding.
+
 ## [1.3.15] - 2026-09-27
 
 The first release with features in it since the bridge got code. Three
@@ -574,6 +948,8 @@ for it, so the number is free; the bridge will use it when the platform does.
   commits, and a squash makes them unreachable from `main` - which would turn
   the check red on `main` for everybody, for something no contributor did.
 
+[1.3.16]: https://github.com/mavrovde/viafrei-bridge/releases/tag/v1.3.16
+[1.3.15]: https://github.com/mavrovde/viafrei-bridge/releases/tag/v1.3.15
 [1.3.12]: https://github.com/mavrovde/viafrei-bridge/releases/tag/v1.3.12
 [1.3.10]: https://github.com/mavrovde/viafrei-bridge/releases/tag/v1.3.10
 [0.0.9]: https://github.com/mavrovde/viafrei-bridge/releases/tag/v0.0.9

package/LICENSE

@@ -210,7 +210,8 @@ bridge in this repository.
 
 Data obtained through the ViaFrei MCP server keeps its own provider licence and
 is not relicensed by anything here. Several of those licences are share-alike
-(DELFI public-transport data is CC BY-SA 4.0) or purpose-limited (MTS-K fuel
+(DELFI public-transport data is Creative Commons Attribution-ShareAlike; its
+catalogue entry states no version — see SOURCES.md) or purpose-limited (MTS-K fuel
 prices are consumer information only, with no redistribution in any form,
 aggregates included).
 

package/NOTICE

@@ -10,15 +10,31 @@ keeps its provider's own terms. Those terms travel with the answer, not with
 this package, and several of them are share-alike or purpose-limited. In
 particular:
 
-  - DELFI public-transport data is CC BY-SA 4.0. Share-alike: anything derived
-    from it inherits the obligation, and it must not be blended into a result
-    carrying a different licence.
+  - DELFI public-transport data is Creative Commons Attribution-ShareAlike. The
+    catalogue record for the realtime feed names no version (see SOURCES.md), so
+    treat the share-alike as applying and do not rely on a version for a
+    derivative. Share-alike reaches ADAPTATIONS, not aggregations: if you
+    recompute, reshape or rearrange the data you must license that under BY-SA -
+    art. 1(a) of the 4.0 text names material "translated, altered, arranged,
+    transformed, or otherwise modified", so a rearrangement is inside the
+    obligation and not outside it - but showing it beside another source's data
+    is an aggregation and puts no obligation on the other source. Which version
+    applies is the open question SOURCES.md sets out; the words above are quoted
+    from 4.0 because that is the text we read.
   - MTS-K fuel prices (Tankerkönig) are consumer information only. No
     redistribution in any form, aggregates and derived tables included.
-  - Address results are derived from OpenStreetMap under the ODbL 1.0. The
-    share-alike is on the database rather than on the sentence, and our offer
-    under section 4.6 stands: ask and you get the extract and our alterations
-    to it under the same licence.
+  - Address, point-of-interest and place results can be derived from
+    OpenStreetMap under the ODbL 1.0. What decides it is which TABLE answered,
+    not which tool you called: place resolution falls through our own gazetteer
+    to the OSM tables, so any answer about a place may be OSM-derived. Read
+    `_meta.sources` and the attribution line on the answer you actually got — an
+    OSM-derived result names `osm`. The share-alike is on the database (ODbL 4.4)
+    and not on the answer (ODbL 4.5(b)); the answer carries a notice instead
+    (ODbL 4.3). Our offer under ODbL 4.6 stands and covers BOTH extracts —
+    addresses and points of interest, one file each — plus our alterations to
+    them, under ODbL 1.0 and free of charge. Ask by opening an issue on this
+    repository, or by the e-mail address in the Impressum at
+    https://viafrei.de/impressum if you have no GitHub account.
   - Autobahn GmbH, BKG, DWD, Deutsche Bahn, GeoNames and the AFIR charging
     feeds each carry their own licence and attribution string.
 

package/README.md

@@ -97,11 +97,18 @@ lorry parking. The table said "car and lorry parking" until this release; it was
 the same over-claim the Rail row carried about disruptions, and it is corrected here rather
 than left for a user to discover.
 
-**No tool names, descriptions or schemas are pasted on this page, on purpose.**
-This file is frozen inside a published tarball and cannot be corrected without a
-release, so a copied catalogue would start rotting the first time a description
-changes on the server. There is one source of truth and it is the running
-server: connect any MCP client and call `tools/list`.
+**No tool names, descriptions or schemas are written by hand on this page, on
+purpose.** This file is frozen inside a published tarball and cannot be corrected
+without a release, so a hand-copied catalogue would start rotting the first time a
+description changed on the server.
+
+**[API.md](API.md) is the way round that, and it is honest about what it is.** It
+is *generated* from [`catalogue.json`](catalogue.json) — a snapshot of what the
+production server answered when asked to describe itself — and CI fails if the two
+have drifted, so the document cannot quietly disagree with the snapshot. What that
+does not fix is the snapshot ageing relative to the live server: a capture is a
+point in time, and API.md's header carries the date it was taken. **The source of
+truth is still the running server**: connect any MCP client and call `tools/list`.
 (<https://viafrei.de> is the live national traffic digest, not a catalogue.)
 
 ## Connect in one line
@@ -147,6 +154,25 @@ Claude Desktop's `claude_desktop_config.json`:
 
 Restart the client and ask it one of the questions above.
 
+## Documentation
+
+| | |
+|---|---|
+| **[API.md](API.md)** | Every tool with its parameters, types, defaults and constraints, plus the resources, resource templates and prompts. Generated from a dated snapshot of the running server, so the descriptions are the server's own words — which is what your assistant actually reads when it picks a tool. |
+| **[Wiki](https://github.com/mavrovde/viafrei-bridge/wiki)** | The prose half: [connecting your assistant](https://github.com/mavrovde/viafrei-bridge/wiki/Connecting-your-assistant), [tools at a glance](https://github.com/mavrovde/viafrei-bridge/wiki/Tools-at-a-glance), the [roadmap](https://github.com/mavrovde/viafrei-bridge/wiki/Roadmap) and an [FAQ](https://github.com/mavrovde/viafrei-bridge/wiki/FAQ). |
+| **[SOURCES.md](SOURCES.md)** | Every publisher, what it covers, its licence, and the attribution line to reproduce — including the conditions that are licence breaches rather than style problems. |
+| **[SUPPORT.md](SUPPORT.md)** | Where a question, a bad answer or a security report should go, and what makes a report easy to act on. |
+
+### Worked use cases
+
+Five walkthroughs, each naming the tools that answer it and what comes back:
+
+- [Driving Munich to Berlin](https://github.com/mavrovde/viafrei-bridge/wiki/Use-case-Driving-Munich-to-Berlin) — briefing a motorway run: several A-roads in one call, roadworks ahead, a fuel or charging stop, parking at the far end.
+- [The commute that broke](https://github.com/mavrovde/viafrei-bridge/wiki/Use-case-The-commute-that-broke) — departures, regional disruption, and a station lift that is out, which is the difference between a step-free route existing and not.
+- [An EV on a long weekend](https://github.com/mavrovde/viafrei-bridge/wiki/Use-case-An-EV-on-a-long-weekend) — charging by connector and power, low-emission-zone rules, what is around a stop.
+- [Fleet and logistics briefings](https://github.com/mavrovde/viafrei-bridge/wiki/Use-case-Fleet-and-logistics-briefings) — a dispatcher's morning brief, watches that report a change instead of being polled, and the one licence rule that bites hardest here.
+- [Building a local guide agent](https://github.com/mavrovde/viafrei-bridge/wiki/Use-case-Building-a-local-guide-agent) — a vague place to coordinates and back, and what OpenStreetMap's licence asks of you.
+
 ## Why build on it
 
 - **One endpoint instead of a stack of integrations.**
@@ -286,9 +312,16 @@ licence breach rather than a style problem:
 - **MTS-K fuel prices are consumer information only.** No redistribution in any
   form — that includes aggregates, comparisons, price tables and anything
   derived. Answer the person who asked; do not build a product out of it.
-- **DELFI public-transport data is CC BY-SA 4.0.** Share-alike travels with
-  anything derived from it, and it must not be blended into a result under a
-  different licence.
+- **DELFI public-transport data is Creative Commons
+  Attribution-ShareAlike.** Share-alike travels with anything you *derive* from
+  it — recompute it, reshape it, rearrange it, build a delay table out of it, and
+  that is Adapted Material you must license under BY-SA (art. 1(a) names material
+  "translated, altered, arranged, transformed, or otherwise modified"). Merely **showing** it beside
+  another source's data is an aggregation, and puts no obligation on the other
+  source; an earlier version of this page said otherwise, which told you a
+  licence forbids something it permits. The catalogue record for the realtime
+  feed names no licence version, so do not rely on one for a derivative —
+  [SOURCES.md](SOURCES.md) has the detail and the open question.
 
 Everything else — where each answer comes from, and what each licence asks of
 you — is in [SOURCES.md](SOURCES.md). See also [NOTICE](NOTICE) and