Feat: Getting an agent's status

[pdaoust]

Closes #537 . Also fixes missing category nav on the tops of all the other pages in the validation category.

NOTE: hold off merging this until 0.6 is the recommended release -- it's got a lot of info about warrants.

Summary by CodeRabbit

• Documentation

  • Added "Getting an Agent's Status" guide (with examples) and added it to Build → Validation and site navigation.
  • Added top-of-page topic lists to multiple Validation pages for easier navigation.
  • Expanded DHT Operations with a new "Warrant operations" overview.
  • Clarified glossary warrant definition and revised entries/links validity guidance.

• Bug Fixes

  • Fixed wording issues and corrected anchors/links in DHT Operations.

• Chores

  • Added markdownlint config (MD007 indent = 4).

[coderabbitai[bot]]

Walkthrough

Adds a new "Getting an Agent's Status" documentation page, links to it from Build → Validation and several validation TOCs, updates DHT operations and glossary with warrant-related content, fixes anchors/typos in DHT docs, clarifies get/get_links behavior, and adds a markdownlint config. All edits are documentation/config only.

Changes

Cohort / File(s)	Summary
Navigation & Validation index updates src/pages/_data/navigation/mainNav.json5, src/pages/build/index.md, src/pages/build/validation.md	Add “Getting an Agent's Status” link under Build → Validation and corresponding bullets in index/validation pages.
New documentation page src/pages/build/getting-an-agents-status.md	Add new page documenting get_agent_activity with Rust examples for checking agent status, warrants, chain status, and a proposal-evaluation example; includes security notes and references.
Validation TOC inserts src/pages/build/validate-callback.md, src/pages/build/genesis-self-check-callback.md, src/pages/build/must-get-host-functions.md	Insert top-of-page "In this section" topic-list blocks linking Validation-related pages; add brief intro text on validate page.
DHT operations doc src/pages/build/dht-operations.md	Add topic-list, fix anchors/typos (StoreEntry, Update, RegisterUpdate, RegisterDeleteLink), and append a “Warrant operations” section describing warrants and retrieval via get_agent_activity.
Glossary edits src/pages/resources/glossary.md	Redefine warrants as signed DHT operation attestations, introduce basis-address, simplify validity conditions, add usage notes and explicit constraint that invalid warrants aren't produced.
Entries & Links docs src/pages/build/entries.md, src/pages/build/links-paths-and-anchors.md	Clarify get requires the entry-creation action hash; add notes that get, get_links, and get_link_details return data valid for the delivering agent and point readers to the new agent-status page.
Querying & architecture text tweaks src/pages/build/querying-source-chains.md, src/pages/concepts/2_application_architecture.md	Link get_agent_activity status text to the new page and fix a typographical error in application architecture doc.
Formatting / lint config .markdownlint.json	Add markdownlint config (MD007 indent: 4).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• holochain/docs-pages#606 — Related documentation changes around get_agent_activity, agent status, and querying source chains (overlapping content and topics).

Suggested reviewers

• ThetaSinner
• matthme
• jost-s

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title "Feat: Getting an agent's status" is concise, focused, and accurately reflects the primary change in this PR — adding documentation and navigation for obtaining an agent's status; it is readable and conveys the main intent to teammates scanning history. The phrasing is specific to the new feature and avoids noisy file lists or vague terms. Overall it summarizes the main change clearly and succinctly.
Linked Issues Check	✅ Passed	The PR implements the core acceptance criteria of linked issue [#537] by adding a dedicated page documenting get_agent_activity, describing warrants and chain status, and including practical Rust examples that obtain warrants and evaluate chain state, plus navigation and cross-reference updates and a merge-hold note while warrants stabilize. The changes supply the requested practical examples and explanatory material about warrants and eventual consistency and link the new page from relevant validation docs. Minor deviations in the provided summaries are that the page also notes that the source chain can be queried and includes an ActivityRequest::Full example and the summaries do not explicitly call out countersigning as the primary use case; these are clarifications rather than substantive omissions.
Out of Scope Changes Check	✅ Passed	Most edits are in-scope documentation changes supporting the new "Getting an Agent's Status" content (new page, navigation updates, glossary and DHT/warrant text, and cross-references). Out-of-scope items are minimal and limited to repository-style or unrelated minor edits such as adding .markdownlint.json and a small typographical fix in concepts/2_application_architecture.md, which do not alter runtime behavior but are not strictly required by issue [#537]. Overall the substantive changes relate to the linked issue and out-of-scope edits are small and low-risk.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment
• [ ] Commit unit tests in branch feat/get-agent-status

[!TIP]

👮 Agentic pre-merge checks are now available in preview!

Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.

• Built-in checks – Quickly apply ready-made checks to enforce title conventions, require pull request descriptions that follow templates, validate linked issues for compliance, and more.
• Custom agentic checks – Define your own rules using CodeRabbit’s advanced agentic capabilities to enforce organization-specific policies and workflows. For example, you can instruct CodeRabbit’s agent to verify that API documentation is updated whenever API schema files are modified in a PR. Note: Upto 5 custom checks are currently allowed during the preview period. Pricing for this feature will be announced in a few weeks.

Please see the documentation for more information.

Example:

reviews:
  pre_merge_checks:
    custom_checks:
      - name: "Undocumented Breaking Changes"
        mode: "warning"
        instructions: |
          Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).

Please share your feedback with us on this Discord post.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pdaoust]

@coderabbitai change your linting rules for Markdown for all PRs in this repository; indentation for bullets should be four spaces, not two.

[coderabbitai[bot]]

[!TIP] For best results, initiate chat on the files or code changes.

🧩 Analysis chain

@pdaoust I'll help you configure the markdown linting rules for this repository. Let me fetch the current CodeRabbit configuration information to provide you with accurate guidance on how to set the bullet indentation to 4 spaces instead of 2.

---

🛠️ Debug Information Gathered

---

@pdaoust Based on the configuration schema, I can see that CodeRabbit uses markdownlint for markdown linting, which is currently enabled in your repository. However, CodeRabbit doesn't provide direct configuration options for specific markdownlint rules like bullet indentation spacing within the CodeRabbit configuration itself.

To configure bullet indentation to use 4 spaces instead of 2 spaces for this repository, you have a few options:

Option 1: Create a .markdownlint.json configuration file

You can create a .markdownlint.json file in the root of your repository to configure markdownlint rules:

{
  "MD007": {
    "indent": 4
  }
}

This configures the MD007 rule (unordered list indentation) to use 4 spaces instead of the default 2 spaces.

Option 2: Use CodeRabbit's path instructions

Alternatively, you can use CodeRabbit's path_instructions feature to provide specific guidance for markdown files. You would need to add this to your CodeRabbit configuration:

reviews:
  path_instructions:
    - path: "**/*.md"
      instructions: "For markdown files, bullet point indentation should use 4 spaces instead of 2 spaces. This applies to all unordered lists."

Option 3: Disable markdownlint MD007 rule and add a learning

If you want CodeRabbit to handle this preference directly, you could disable the MD007 rule in markdownlint and add a learning for me to remember this preference.

Recommendation

I recommend Option 1 - creating a .markdownlint.json file, as this is the most direct way to configure markdownlint's behavior for your specific indentation preference. This will ensure that both CodeRabbit's markdownlint integration and any local markdownlint usage follow your preferred 4-space indentation rule.

Would you like me to help you create the .markdownlint.json file, or would you prefer one of the other options?

---

🧠 Learnings used

Learnt from: pdaoust
PR: holochain/docs-pages#594
File: src/pages/resources/howtos/running-network-infrastructure.md:178-185
Timestamp: 2025-07-31T17:05:08.265Z
Learning: pdaoust prefers to ignore the MD047 rule (files should end with a single newline character) in the holochain/docs-pages repository because it's not applicable to the admonition plugin they're using.

[ThetaSinner]

Something that might be worth adding to this documentation is about blocking:

• When authorities get a warrant and validate it, they're supposed to block the author if the warrant is valid. Equally, discovering a validation failure and issuing a warrant is also supposed to result in the author being blocked.
• When getting a sticky warrant by fetching a warranted op or an op authored by a warranted agent (I don't actually know which it is off the top of my head, I'd have to look at this), that warrant should get stored and validated and the author should be blocked.
• In the special case of discovering a warrant through get_agent_activity, Holochain could also store and check the warrant and block the author for you.

No blocking is currently implemented but it is really the point of warrants, to exclude the author from the network. I think that'd be worth mentioning in this page at some point. We're still implementing it though so perhaps it's something to do when the details are ready?

[pdaoust]

Thanks!

I didn't find it that easy to track the diffs for this one

sorry, yeah, some of the feedback necessitated some rather extensive rewrites, and I'm sure they overlapped on each other.

[cocogitto-bot[bot]]

:heavy_check_mark: 7dab8c87f03af645fd4ffd2dc80b5462f7c30764...0ad92b76dc18b4ca710532270383f0ff3db2eb94 - Conventional commits check succeeded.