[schronck]

Summary

Users had no guide for the three ways DecMan decentralizes a party. This PR adds one task guide for each case, and fixes docs that had drifted from the code.

New and rewritten guides

• docs/ADDING_A_MEMBER_TO_A_DECENTRALIZED_PARTY.md (new) covers the add-party workflow. It lists the prerequisites, the UI and API steps, and the threshold rule. It also covers the joining node's downtime, re-adding a former member, failed runs, and quarantine.
• docs/DECENTRALIZING_AN_EXTERNAL_PARTY.md (new) covers a wallet-held party. It explains host setup and how to sign a hash. It also covers creating a party, adding hosts, copying the contracts, raising the threshold, and errors.
• docs/DECENTRALIZING_AN_EXISTING_PARTY.md (rewritten) now covers local parties only. It explains failover and co-validation, gives the curl steps for each, and shows which node signs what.

Each guide warns that the party must stay idle while a joining host is hosted but not yet importing. The add-party workflow disconnects the joiner before its hosting takes effect. The tenant add-hosts path does not, which is the order that crashed a MainNet participant on 2026-09-16.

Stale docs fixed

• The README and the Deployment Guide now list DECPM_TENANT_API_KEYS, DECPM_AUTH0_SCOPE and DECPM_JWT_ROLE_CLAIM. The README route table now lists add-hosts/authorize and threshold/authorize.
• The ARCHITECTURE step tables for kick, add-party and change-threshold now include RetireLegacyKeys. The add-party table now gives the current disconnect order.
• The ARCHITECTURE scope note no longer says that the tenant API cannot decentralize a party with contracts.
• The wallet README's failover section said HostPermission::Submission gives a wallet-held party failover. It now says that Confirmation hosting already does.
• An orphaned doc comment in cli.rs and config.rs is gone. Clap printed it as the --help text of DECPM_REWARD_EXPIRY_READ_INTERVAL_SECS.

Related issues

None. The code problems found while writing these guides are listed under notes for reviewers.

Type of change

• Bug fix
• New feature
• Refactor
• Documentation
• Build / CI / chore

Checklist

• cargo fmt -- --check passes
• cargo clippy --all-targets --all-features -- -D warnings is clean
• cargo test passes. Not run: the only Rust change removes doc comments
• Added/updated tests where appropriate
• Updated documentation where appropriate
• Commits follow the <type>(<scope>): <subject> convention

How it was checked

• Every relative link and anchor in the changed docs resolves.
• dec-party-manager serve --help now prints the right text for --reward-expiry-read-interval-secs.
• The local-party steps follow the procedure that ran on DevNet on 2026-10-08, for both failover and co-validation.

Notes for reviewers

The guides document current behaviour. These code problems turned up on the way, and none of them is fixed here:

1. The tenant add-hosts path disconnects the joiner at import time, not before its hosting takes effect.
2. DecMan cannot change an existing host's permission. So a local party with failover hosts cannot move to co-validation.
3. HostPermission::Submission in decman-wallet has no party it can serve. A wallet-held party has its own key, and a local party needs authorize.
4. /v0/tenant/{party}/status answers 404 for a Submission host.
5. The last import block answers 500 when Canton already has a marker clear pending.
6. The Add Member dialog allows a threshold up to N+1, but the server accepts at most N.
7. The UI step lists for add-party, kick and change-threshold lack RetireLegacyKeys, so their pipelines show no labels.
8. The UI points to a "Network Configuration" page that does not exist, and its Swagger hint names serve --test instead of --insecure.
9. Cancelling a failed add-party run leaves the new member disconnected, with its synchronizer on manual connection.
10. DELETE /acs-import-quarantine has no admin-role check.

[Copilot]

🟡 Changes recommended

Several guide instructions currently use invalid serials, mishandle per-host credentials, or prescribe an unrecoverable new workflow run.

3 open findings

• Re-read the serial after onboarding before threshold authorization · New
• Use per-host tenant keys in multi-host authentication · New
• Link wallet-held parties directly to the external-party guide · New

What changed in this PR

Adds practical guides for DecMan’s three party-decentralization workflows and aligns existing documentation with current behavior.

Changes:

• Adds guides for decentralized-party membership and wallet-held parties.
• Rewrites local-party guidance and updates architecture/configuration references.
• Removes orphaned Rust doc comments affecting CLI help.

File	Description
USER_GUIDE.md	Links the new task guides.
README.md	Updates documentation, configuration, and API references.
docs/​USE_CASES.md	Clarifies add-member constraints and recovery guidance.
docs/​DEPLOYMENT_GUIDE.md	Documents tenant API keys.
docs/​DECENTRALIZING_AN_EXTERNAL_PARTY.md	Adds the wallet-held party guide.
docs/​DECENTRALIZING_AN_EXISTING_PARTY.md	Rewrites guidance for local parties.
docs/​ARCHITECTURE.md	Updates workflow steps and tenant API scope.
docs/​ADDING_A_MEMBER_TO_A_DECENTRALIZED_PARTY.md	Adds the decentralized-party membership guide.
crates/​decman/​src/​config.rs	Removes a misplaced doc comment.
crates/​decman/​src/​cli.rs	Corrects generated CLI help by removing an orphaned comment.
crates/​decman-wallet/​README.md	Corrects failover-hosting guidance.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[scolear]

Reviewed d5fe2a1.

I checked the named routes and settings against the code at main. Every /v0/tenant/* route in the three guides exists, with the /execute names from #521. DECPM_TENANT_API_KEYS, DECPM_AUTH0_SCOPE, DECPM_JWT_ROLE_CLAIM and DECPM_EXTERNAL_PARTIES_TTL_SECS all exist in cli.rs. The add-party body and the threshold rule match AddPartyRequest and the check in workflows.rs. The re-add rule matches the error text in proposals/create.rs. The tenant-key gate in middleware/auth.rs works as the README describes. The RetireLegacyKeys steps are correct.

The 308 removed lines are the old external-party content of DECENTRALIZING_AN_EXISTING_PARTY.md. The new external-party guide carries the relay rules, the no-resume rule, the idle reap, marker_cleared and RepairCommitmentsUsingAcs. The warning that the owner node can revoke a converted party's key stays in the local-party guide. Two items are gone from every guide: the /onboard to /execute rename note, and the fetched_at and refreshing polling rule for /external-parties. The rename note was a migration note, so its loss is fine. The polling rule is small, and the TTL setting is still in the README. Neither blocks.

The only Noise mention is the status text that the UI shows today. The guides do not present Noise as the long-term design.

Approve.