[Docs] Add secure human readable naming

[adamtagscherer]

There is a new featured merged into the DIR's main branch that needs to be documented.
Feature: agntcy/dir#638

[adamtagscherer]

Name Verification

Name verification proves that the signing key is authorized by the domain claimed in the record's name field.

Requirements

• Record name must include a protocol prefix: https://domain/path or http://domain/path
• A JWKS file must be hosted at <scheme>://<domain>/.well-known/jwks.json
• The record must be signed with the private key corresponding to a public key present in that JWKS file

Workflow

1. Push a record with a verifiable name:

   dirctl push record.json --output raw
   # Returns: bafyreib...

2. Sign the record (triggers automatic verification):

   dirctl sign <cid> --key private.key

3. Check verification status:

   # By CID
   dirctl naming verify <cid> --output json
   
   # By name
   dirctl naming verify cisco.com/agent --output json
   
   # By name with version
   dirctl naming verify cisco.com/agent:v1.0.0 --output json

Verification Response

{
  "cid": "bafyreib...",
  "verified": true,
  "domain": "cisco.com",
  "method": "jwks",
  "key_id": "key-1",
  "verified_at": "2026-01-21T10:30:00Z"
}

---

Name-to-CID Resolution

CLI commands now support Docker-style name references instead of requiring CIDs.

Supported Reference Formats

Format	Description
<cid>	Direct lookup by content address
<name>	Resolves to the most recently created version
<name>:<version>	Resolves to a specific version
<name>@<cid>	Hash-verified lookup (fails if resolved CID doesn't match)
<name>:<version>@<cid>	Hash-verified lookup for a specific version

Updated Commands

dirctl pull

# Pull by CID (existing)
dirctl pull bafyreib...

# Pull by name (latest version)
dirctl pull cisco.com/agent

# Pull by name with specific version
dirctl pull cisco.com/agent:v1.0.0

# Pull with hash verification
dirctl pull cisco.com/agent@bafyreib...
dirctl pull cisco.com/agent:v1.0.0@bafyreib...

dirctl info

# Info by CID (existing)
dirctl info bafyreib...

# Info by name (latest version)
dirctl info cisco.com/agent --output json

# Info by name with specific version
dirctl info cisco.com/agent:v1.0.0 --output json

dirctl naming verify

# Verify by CID (existing)
dirctl naming verify bafyreib...

# Verify by name (latest version)
dirctl naming verify cisco.com/agent

# Verify by name with specific version
dirctl naming verify cisco.com/agent:v1.0.0

Hash Verification

The @<cid> suffix enables hash verification - the command fails if the resolved CID doesn't match the expected digest:

# Succeeds if cisco.com/agent:v1.0.0 resolves to bafyreib...
dirctl pull cisco.com/agent:v1.0.0@bafyreib...

# Fails with error if CIDs don't match
dirctl pull cisco.com/agent@wrong-cid
# Error: hash verification failed: resolved CID "bafyreib..." does not match expected digest "wrong-cid"

Version Resolution Behavior

When no version is specified, commands return the most recently created record (by record's created_at filed). This allows non-semver tags like latest, dev, or stable.