FE-1056: Improve Petrinaut Handle + Integration Docs

[kube]

🌟 What is the purpose of this PR?

Updates on Petrinaut Handle creation, and documentation for integration into host applications.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• does not modify any publishable blocks or libraries, or modifications do not need publishing
• modifies an npm-publishable library and I have added a changeset file(s)

📜 Does this require a change to the docs?

The changes in this PR:

• require changes to docs which are made as part of this PR

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• do not affect the execution graph

⚠️ Known issues

• Petrinaut Handle interface is still experimental and may change in future versions.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
petrinaut	Ready	Preview	Aug 4, 2026 10:35am

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
hash	Ignored	Preview	Aug 4, 2026 10:35am
hashdotdesign-tokens	Ignored	Preview	Aug 4, 2026 10:35am

[semgrep-code-hashintel]

Semgrep found 4 path-join-resolve-traversal findings:

• .claude/setup.mjs
  • L223 - Triage
  • L223 - Triage
  • L257 - Triage
  • L257 - Triage

Detected possible user input going into a path.join or path.resolve function. This could possibly lead to a path traversal vulnerability, where the attacker can access arbitrary files stored in the file system. Instead, be sure to sanitize or validate user input first.

View Dataflow Graph

flowchart LR
    classDef invis fill:white, stroke: none
    classDef default fill:#e7f5ff, color:#1c7fd6, stroke: none

    subgraph File0["<b>.claude/setup.mjs</b>"]
        direction LR
        %% Source

        subgraph Source
            direction LR

            v0["<a href=https://github.com/hashintel/hash/blob/3c80fef937ed2cd8869428222504b8915ebc22eb/.claude/setup.mjs#L226 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 226] _0x2912ea</a>"]
        end
        %% Intermediate

        subgraph Traces0[Traces]
            direction TB

            v2["<a href=https://github.com/hashintel/hash/blob/3c80fef937ed2cd8869428222504b8915ebc22eb/.claude/setup.mjs#L226 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 226] _0x2912ea</a>"]
        end
        %% Sink

        subgraph Sink
            direction LR

            v1["<a href=https://github.com/hashintel/hash/blob/3c80fef937ed2cd8869428222504b8915ebc22eb/.claude/setup.mjs#L257 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 257] _0x2912ea</a>"]
        end
    end
    %% Class Assignment
    Source:::invis
    Sink:::invis

    Traces0:::invis
    File0:::invis

    %% Connections

    Source --> Traces0
    Traces0 --> Sink

Loading