STRAZAdocs
Markdown

Knowledge packs

A role carries a knowledge pack, and every agent session of that role starts with the pack's text in its context.

Who
Admin
Where
Terminal, the console, and the agent's machine

In short

A knowledge pack is text you write once and bind to an application or business role. Every agent session of a holder of that role starts with the text in its context, right after the Straza banner. Creating, binding and deleting a pack writes no audit record yet.

On this page

A knowledge pack is a piece of text you write once and bind to a role. Every agent session of a person who holds that role starts with the text in its context, right after Straza’s banner. Use it for what an agent should know about your team, such as where it may deploy and which tests to run. A pack tells the agent things and enforces nothing, so a rule that must hold belongs in a policy.

Creating, binding, unbinding or deleting a pack writes no audit record today.

Before you start

  • strazactl on an admin API token in STRAZA_API_TOKEN, minted in the console as Mint an admin API token shows. Packs belong to the identity area of the admin API, so the token needs identity:read and identity:write.
  • A role of kind application or business to carry the pack. The examples use dev, which alice holds.
  • A machine enrolled as alice, as Enroll a machine shows, to see the result.
  1. Write the pack

    A pack is plain text, and Markdown reads well to a model. Save the text each session should start with as team-conventions.md. Keep it short, because it rides in the context of every session of the role.

    Use the staging cluster for every deploy. Production deploys go through the release pipeline, never from a laptop.
    Run the unit tests before you propose a commit.
  2. Create the pack

    CLI only

    The console binds and unbinds packs and cannot create one, so this step runs in a terminal.

    Terminal administration
    strazactl packs create team-conventions --file team-conventions.md

    You should see

    created pack team-conventions (01a112c9-a801-7d18-9f24-b211accab334) with your own id.

    A pack’s name is unique. --version sets the label the agent sees next to the name, 1 by default, and --content takes the text inline in place of a file. strazactl packs list shows each pack with its version and size:

    NAME              VERSION  BYTES  ID
    team-conventions  1        163    01a112c9-a801-7d18-9f24-b211accab334
    If this fails
    pack already exists
    A pack of that name exists. Pick another name, or replace the pack as the last step shows.
  3. Bind it to a role

    Open the role’s page, go to its Knowledge packs tab, pick the pack and bind it.

    1. Roles
    2. dev
    3. Knowledge packs
    4. Pick a pack
    5. team-conventions
    6. Bind pack
    The dev role page, tab Knowledge packs, with team-conventions picked and the button Bind pack The dev role page, tab Knowledge packs, with team-conventions picked and the button Bind pack
    The Knowledge packs tab of dev, with team-conventions picked and Bind pack. Show the whole screen

    You should see

    dev receives team-conventions now.

    The tab shows on the page of an application or business role once at least one pack exists. The New role wizard has a Knowledge packs step as well. A draft never binds a pack, so the wizard binds the packs you pick when you press Save and publish.

    Terminal administration
    strazactl packs bind team-conventions dev

    You should see

    bound the knowledge pack team-conventions to role dev

    Each session receives the packs of every role its person holds, a role held through another role that composes it included. So a person who holds a business role web-team that composes dev receives team-conventions as well. Approver roles and Straza roles carry no packs.

    If this fails
    approver role: it decides approval requests and cannot carry knowledge packs
    Bind the pack to an application or business role instead.
    Straza role: it governs Straza itself and cannot carry knowledge packs
    Bind the pack to an application or business role instead.
    no pack named "team-conventions"
    strazactl finds a pack by its name. Check the name with strazactl packs list.

    strazad stores each pack with a checksum of its text, and a session’s check-in answer carries the pack with that checksum.

  4. See it at the next session start

    A pack reaches an agent when its session starts. On alice’s machine, open a session the way a harness does when it starts.

    Terminal on alice's machine
    printf %s '{"hook_event_name":"SessionStart"}' | straza hook --harness claude-code

    You should see

    The context ends with # Straza knowledge packs (delivered by role) and the pack under its name and version.

    The context the agent receives, decoded from the hook’s JSON answer, reads:

    Straza governs this session as "alice". Every tool call is checked against policy and recorded in the audit log. When a call is denied, tell the user what the reason says, then do what it says next: wait for a person's approval, change the call, or try once more later. A denial that says none of these is a policy decision, and the same call will be denied again. Do not try to reach the denied result another way.
    
    # Straza knowledge packs (delivered by role)
    
    ## team-conventions (v1)
    
    Use the staging cluster for every deploy. Production deploys go through the release pipeline, never from a laptop.
    Run the unit tests before you propose a commit.

    A session that is already running keeps the packs it started with, so a pack you bind or unbind reaches the agent at its next session start. Packs arrive through the session-start hook of Claude Code, Codex and Gemini. A client that reaches Straza only through the gateway, with straza mcp, receives no pack.

  5. Unbind the pack

    1. Roles
    2. dev
    3. Knowledge packs
    4. Unbind
    5. Unbind pack

    The dialog says Sessions holding dev stop receiving team-conventions at their next check-in. The pack itself is kept.

    You should see

    dev no longer receives team-conventions.

    Terminal administration
    strazactl packs unbind team-conventions dev

    You should see

    unbound the knowledge pack team-conventions from role dev

  6. Delete or replace the pack

    CLI only

    The console cannot delete a pack, so this step runs in a terminal.

    Delete a pack once no role carries it. Without --yes, strazactl asks before it deletes.

    Terminal administration
    strazactl packs delete team-conventions --yes

    You should see

    deleted knowledge pack team-conventions

    If this fails
    the knowledge pack is still bound to the role dev, and deleting it would change what that role's sessions receive. Unbind it from the role first, then delete it
    Unbind the pack from each role the sentence names, then delete it.

    A pack has no edit. To change its text, unbind it, delete it, create it again from the new file, and bind it again. Sessions that start after that receive the new text.

Next

Walked on v1.1.0-117-g106081a8 on 2026-10-06, except the console steps, read in the console source and not clicked.

An Alpine Linux container against a standalone server, with strazactl as the admin and the session start piped into straza hook as alice. The console steps were read in the console source, not clicked. Console screenshots show strazad v1.0.0-1753-ga27c516c, standalone.

Search documentation

Search page titles, commands, and article text.

↑ ↓ Choose resultEnter OpenEsc Close