Skip to content

docs(cli): the node ladder prefers your own node; document --local and the no-node error - #61

Merged
MichaelTaylor3d merged 3 commits into
mainfrom
docs/2099-local-origin
Aug 5, 2026
Merged

docs(cli): the node ladder prefers your own node; document --local and the no-node error#61
MichaelTaylor3d merged 3 commits into
mainfrom
docs/2099-local-origin

Conversation

@MichaelTaylor3d

@MichaelTaylor3d MichaelTaylor3d commented Aug 4, 2026

Copy link
Copy Markdown
Contributor

Documents the behaviour shipping in DIG-Network/digs#37
(dig_ecosystem#2099). Docs and code land together per §4.3 — this is the same unit of work, not a
follow-up.

digs used to default to rpc.dig.net. It now prefers your own node, can be pinned per project,
and refuses to publish through a server you never chose. The docs said none of that.

What changed

docs/digstore/cli/command-reference.md

  • The config node.url table gains the --local (per-project), --show, and --unset forms.
  • The resolution ladder now names all four tiers precisely — including that the project value sits
    between $DIG_NODE_URL and the machine-wide value, and that dig.local is tried over HTTPS then
    HTTP, with localhost on 9778/$DIG_NODE_PORT.
  • States plainly that your own node comes first: rpc.dig.net is an ordinary node that happens to
    be well known, not a privileged one (dig_ecosystem#1997).
  • New "Setting a node per project" — including why a repo-carried node.url is not honoured
    until you approve it: .dig/node.toml arrives with a cloned repository, and digs signs every
    request to a node with your identity key. Explains that approving one project does not approve
    another, that an edited value re-asks, and that a non-interactive run ignores it.
  • New "When no local node is running" — reading still works and says so; publishing stops with
    NO_LOCAL_NODE (exit 19), with the real commands (dig-node status, dig-node start) and where
    to install.

docs/rpc/dig-remote.md — the same ladder, corrected in the dig:// host-resolution section,
plus that an unconfigured origin now means your node.

docs/run-a-node/point-a-consumer.md — one line aligned with the above.

Accuracy

Written against the shipped behaviour and the installed binary rather than from the design. Every
command and URL the pages tell a stuck user to run was checked, with a control so the check could
fail:

https://dig.net/install.sh              200
https://dig.net/install.ps1             200
https://docs.dig.net/docs/run-a-node    200
https://docs.dig.net/docs/<bogus>       404   <- control
dig-node status / dig-node start        both exist as subcommands

Per §4.3 these pages stay self-contained: no reference to SPEC.md, SYSTEM.md, or issue numbers —
the reasoning is stated directly, in the user's terms.

Version

0.11.10.12.0 — minor: new documented capability.

@MichaelTaylor3d
MichaelTaylor3d force-pushed the docs/2099-local-origin branch 2 times, most recently from c6654d4 to 1246837 Compare August 4, 2026 23:47
MichaelTaylor3d and others added 3 commits August 4, 2026 17:58
…d the no-node error

digs defaults to the local node rather than rpc.dig.net, so the published
ladder needed to say so, and two new behaviours needed documenting:

- `digs config node.url --local <url>` sets a per-project node in
  .dig/node.toml, and that file is NOT trusted on sight because it can arrive
  with a cloned repository.
- With no local node, reads fall through to the gateway with a notice while
  push/revoke stop with NO_LOCAL_NODE, so the docs now give the check command
  and the install links.

Also corrects the ladder's addresses to the ones dig-node actually binds
(portless dig.local; plaintext localhost:9778).

Refs DIG-Network/dig_ecosystem#2099

Co-Authored-By: Claude <noreply@anthropic.com>
The resolution section claimed 'connections to any tier use mTLS with a client
certificate derived from your identity key'. That is not what ships:
`digstore-remote`'s TransportMode marks Mtls NOT YET WIRED and the resolver
refuses it, so every tier is reached over plain HTTPS (loopback over plain
HTTP) with the §21.9 signed identity headers doing the authenticating.

Telling a reader their traffic is mutually authenticated when it is not is the
kind of docs error that changes what someone is willing to send. Corrected to
describe what ships, and to say mTLS is specified-but-pending rather than
dropping the mention.

Co-Authored-By: Claude <noreply@anthropic.com>
The same over-claim as the command-reference page, twelve lines below a list I
had already rewritten: 'Connections to any of the three tiers use mTLS,
presenting a client certificate derived from your identity key'.
TransportMode::Mtls is NOT YET WIRED and the resolver refuses it, so what
authenticates a request today is the §21.9 signature, not the transport.

Same replacement applied, so both pages now say the same true thing.

Co-Authored-By: Claude <noreply@anthropic.com>
@MichaelTaylor3d
MichaelTaylor3d force-pushed the docs/2099-local-origin branch from 1246837 to ff70deb Compare August 5, 2026 00:58
@MichaelTaylor3d
MichaelTaylor3d merged commit 11521d3 into main Aug 5, 2026
7 checks passed
@MichaelTaylor3d
MichaelTaylor3d deleted the docs/2099-local-origin branch August 5, 2026 01:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant