feat(docs): Expanded Documentation for signed documents

.config/dictionaries/project.dic

@@ -52,6 +52,7 @@ ciphertexts
 Coap
 codegen
 codepoints
+Collab
 connexa
 coti
 coverallsapp

.earthlyignore

@@ -0,0 +1,2 @@
+.git
+**/target

AGENTS.md

@@ -0,0 +1,95 @@
+# AGENTS – Guidelines for Automated Assistants
+
+This file provides repo‑wide guidance for automated coding assistants working in
+`catalyst-libs`.
+It applies to the entire repository unless a more specific
+`AGENTS.md` exists in a subdirectory.
+
+## General Principles
+
+* Make **small, targeted changes** that directly address the user’s request.
+* Prefer **clarity and correctness** over cleverness; do not refactor broadly
+  unless explicitly asked.
+* Keep existing project structure, naming, and file layout intact unless there
+  is a strong reason to change it.
+* When in doubt about intent (spec vs implementation vs docs), **ask the user**
+  rather than guessing.
+
+## Documentation & Specs
+
+* For architecture/spec docs under `docs/src/architecture` that have a matching
+  Jinja source under `specs/generators/pages`, treat the **Jinja template as the
+  source of truth**.
+    * Example: if both
+    `specs/generators/pages/signed_doc/voting_process/foo.md.jinja` and
+    `docs/src/architecture/08_concepts/signed_doc/voting_process/foo.md`
+    exist, edit the `.md.jinja` file, not the generated `.md`.
+* Follow existing Markdown style:
+    * Respect the “one sentence per line” convention where it is used.
+    * Keep headings, link styles, and admonitions consistent with nearby text.
+* When adding terminology that is likely to trigger the spell checker, add it
+  to `.config/dictionaries/project.dic` in **sorted order**.
+* If the user asks for validation, suggest or run (with their consent):
+    * `just check-markdown`
+    * `just check-spelling`
+
+## Python (spec generators and tooling)
+
+* Python code lives primarily under `specs/generators` and is linted/formatted
+  with `ruff` (see `ruff.toml`).
+* Conform to the existing style:
+    * Use double quotes for strings.
+    * Keep line length within the configured limit.
+    * Do not introduce new global `ignore` rules in `ruff.toml` unless the user
+      requests it.
+* Where sensible, keep functions small and focused; avoid introducing new
+  dependencies without discussing with the user.
+* When the user wants checks run, prefer:
+    * `just format-python-code`
+    * `just lint-python`
+
+## Rust Workspace
+
+* The Rust workspace is in `rust/`.
+  Follow the existing module layout and
+  crate boundaries; do not split or merge crates without explicit direction.
+* Match the existing style and patterns:
+    * Use `cargo fmt` / the configured `fmtfix` and lint commands indirectly
+      via `rust/Justfile` where possible.
+    * Avoid adding new crates to the workspace unless clearly justified.
+* For validation, and only when the user is ready for longer commands, suggest
+  or run:
+    * `cd rust && just code-format`
+    * `cd rust && just code-lint`
+    * `cd rust && just pre-push` (heavier, CI‑like checks)
+
+## CUE/CDDL Specs and Generated JSON
+
+* Specification source is primarily in `specs/definitions` (CUE, CDDL, etc.).
+  Treat these as **normative** and make changes carefully and incrementally.
+* Where both a CUE definition and a JSON spec exist (e.g. `specs/signed_doc.json`),
+  assume the JSON is **generated** from the CUE/source definitions.
+    * Prefer editing the source definitions and let the project’s existing
+      tooling regenerate derived artifacts.
+    * Do not hand‑edit large generated JSON files unless explicitly instructed.
+
+## Earthly, Just, and CI
+
+* This repo uses Earthly (`Earthfile`s) and `just` for repeatable workflows.
+* Respect the intended execution context:
+    * Targets or functions marked as `LOCALLY` are meant to run on the host, not
+      inside container builds.
+    * Do not try to retrofit such targets into containerized steps without a
+      clear reason and user confirmation.
+* When adding new Earthly targets or Just recipes, mirror the style of
+  existing ones and keep names short and descriptive.
+
+## Things to Avoid
+
+* Do not:
+    * Change licensing files, `CODE_OF_CONDUCT.md`, or security policies.
+    * Introduce breaking API changes (in Rust or Python) without calling that
+      out explicitly to the user.
+    * Mass‑reformat the entire repo; limit formatting to files you touch.
+* Avoid speculative “cleanup” in areas unrelated to the user’s request, even
+  if you notice possible improvements; mention them in your summary instead.

Earthfile

@@ -3,7 +3,7 @@ VERSION 0.8
 IMPORT github.com/input-output-hk/catalyst-ci/earthly/mdlint:v3.6.1 AS mdlint-ci
 IMPORT github.com/input-output-hk/catalyst-ci/earthly/cspell:v3.6.1 AS cspell-ci
 IMPORT github.com/input-output-hk/catalyst-ci/earthly/python:v3.6.1 AS python-ci
-IMPORT github.com/input-output-hk/catalyst-ci:v3.6.0 AS cat-ci
+IMPORT github.com/input-output-hk/catalyst-ci:v3.6.1 AS cat-ci
 
 FROM debian:stable-slim
 

docs/src/architecture/08_concepts/signed_doc/docs/proposal.md

@@ -40,6 +40,24 @@ from the [`collaborators`](../metadata.md#collaborators) list.
 All versions of the document *MUST* list the author as the original author.
 The Author can not be changed by any document revision.
 
+Any Proposal that lists a collaborator is an invitation for that collaborator to participate in the proposal.
+They are considered to have accepted that invitation for **all** versions of the proposal that
+list them as a collaborator where their latest
+[Proposal Submission Action](proposal_submission_action.md) for that proposal has an `action` of
+`draft` or `final`.
+
+If a collaborator’s latest [Proposal Submission Action](proposal_submission_action.md) for the
+proposal has an `action` of `hide`, they **MUST** be treated as not having agreed to collaborate
+for **any** version of that proposal (past, present, or future) until they later submit `draft`
+or `final` again.
+
+However, any `final` [Proposal Submission Action](proposal_submission_action.md)
+referencing a proposal **MUST** be published by all collaborators
+listed on the specific version being submitted, in addition to the author.
+
+The `final` proposal itself may be signed by one or more Collaborators and/or the original Author.
+The `final` proposal must never be signed by anyone else.
+
 ### Business Logic
 
 #### Front End

docs/src/architecture/08_concepts/signed_doc/docs/proposal_submission_action.md

@@ -17,6 +17,16 @@ for the same document.
 Unless they all submit the same version of the proposal
 the proposal will not be seen as submitted.
 
+The required set of signers for a submitted proposal version is:
+
+* The original author of the proposal (the signer of the first version where
+  [`id`](../metadata.md#id) == [`ver`](../metadata.md#ver)); and
+* Every collaborator listed in [`collaborators`](../metadata.md#collaborators) on the **exact**
+  version of the proposal referenced by [`ref`](../metadata.md#ref).
+
+They may jointly sign a single Proposal Submission Action, or may submit multiple independent
+Submission actions for the same document (which avoids the need for multi-sig coordination).
+
 The payload is a fixed format.
 
 <!-- markdownlint-disable max-one-sentence-per-line -->
@@ -52,20 +62,30 @@ they can take appropriate action, such as:
 * Remove themselves permanently as a collaborator by publishing a new version with them removed.
 
 To eliminate the necessity for collaborators to accept collaboration on every version,
-they will be considered as agreeing to be a collaborator on any version of the document
-that lists them, if their latest submission is `draft` or `final`.
+they will be considered as agreeing to be a collaborator on **any** version of the proposal that
+lists them in [`collaborators`](../metadata.md#collaborators), if their latest submission for that
+proposal is `draft` or `final`.
 
-If their latest submission on a document is `hide` they should be considered to not
-have agreed to be a collaborator.
+If their latest submission on a proposal is `hide` they **MUST** be considered to not have agreed
+to be a collaborator for **any** version of that proposal (past, present, or future) until they
+submit a new `draft` or `final` action.
 
 *NOTE* `final` status ONLY applies to the exactly referenced document and version.
 
 #### Back End
 
-A Submitted proposal with collaborators *MUST* have
-a `final` submission by *ALL* listed [`collaborators`](../metadata.md#collaborators).
-If any `collaborator` has not submitted a `final` submission by the deadline, then the proposal
-is not considered `final` and will not be considered in the category it was being submitted to.
+A Submitted proposal with collaborators *MUST* have, by the configured deadline:
+
+* A `final` submission from the author; and
+* A `final` submission from **every** collaborator listed in
+  [`collaborators`](../metadata.md#collaborators) on the version of the proposal
+  referenced by [`ref`](../metadata.md#ref); and
+* No required signer whose latest submission for that proposal is `hide`.
+
+If any required collaborator has not submitted a `final` submission for that proposal
+version by the deadline, or if any required signer’s latest submission is `hide`,
+then the proposal is not considered `final` and will not be considered in the
+category it was being submitted to.
 
 ## [COSE Header Parameters][RFC9052-HeaderParameters]
 

docs/src/architecture/08_concepts/signed_doc/voting_process/.pages

@@ -2,5 +2,7 @@ title: Voting Process
 nav:
   - Parameters Hierarchy and Pub/Sub Discovery: parameters_hierarchy_and_discovery.md
   - Proposals, Templates, and Pub/Sub Discovery: proposals_templates_and_discovery.md
+  - dRep Delegation, Nominations, and Discovery: drep_delegation_and_discovery.md
+  - Voting, Bulletin Board, and Pub/Sub Tally: voting_bulletin_board_and_pubsub_tally.md
   - Voting Protocol Cryptography Schema: crypto.md
   - Jörmungandr Voting Transaction (Historical): jormungandr_vote_format_historical.md