Skip to content

docs(readme): rewrite the v2.0 section around what the user gains - #259

Merged
killertcell428 merged 1 commit into
masterfrom
docs/readme-v2-value
Aug 24, 2026
Merged

docs(readme): rewrite the v2.0 section around what the user gains#259
killertcell428 merged 1 commit into
masterfrom
docs/readme-v2-value

Conversation

@killertcell428

Copy link
Copy Markdown
Owner

Why

The previous heading — "one role file, two generated permission files" — described the mechanism, not the benefit. It invited exactly the questions it should have answered: so what if two files got generated? Is the count the point? Did permission settings not exist before?

What changed

Leads with the outcome instead: give each team its own permissions without writing config by hand. Then answers the "why is that good" with numbers measured from an actual run of aigis profile build profiles/marketing.json:

input profiles/marketing.json — 15 lines, 6 choices
output aigis-policy.yaml — 191 lines, 30 rules
output .claude/settings.json — 26 permission rules
reported 10 of the 30 rules that can't be expressed in Claude Code's syntax

Four things the reader gets, each concrete:

  1. No rules to write by hand (6 choices → 56 rules)
  2. Rules that can't be translated exactly are reported with a reason, not approximated into something looser
  3. aigis profile show output is readable by the person who approves it, unlike 191 lines of YAML
  4. --managed produces the managed-settings.json form that no other settings level can override

Also states plainly why there are two layers at all — Claude Code evaluates its own permission rules before any hook runs — since "why 2" was the unanswered question in the old text.

Verification

Numbers came from running the command, not from the docs:

$ aigis profile build profiles/marketing.json
  Wrote aigis-policy.yaml (30 rules)
  Wrote .claude/settings.json (26 permission rules)
  10 policy rule(s) could not be expressed as Claude Code permissions...

Test plan

  • Every number in the section verified against actual command output
  • --managed flag confirmed present on profile build (aigis/cli.py:330)
  • Docs-only change

The previous heading ("one role file, two generated permission files")
described the mechanism, not the benefit — it invited "so what if two
files got generated?" Rewritten to lead with the outcome: give each team
its own permissions without hand-writing config.

Replaces the abstract framing with measured numbers from an actual run
of `aigis profile build profiles/marketing.json`:

  input   profiles/marketing.json     15 lines, 6 choices
  output  aigis-policy.yaml          191 lines, 30 rules
  output  .claude/settings.json       26 permission rules
  reported 10 of 30 rules that can't be expressed in Claude Code syntax

Also states the two things the Claude Code layer is actually for, which
the old text left implicit: it is evaluated before any hook runs, and
`--managed` produces the managed-settings.json form that no other
settings level can override.

Signed-off-by: killertcell428 <killertcell428@gmail.com>
@killertcell428
killertcell428 merged commit c95bf15 into master Aug 24, 2026
11 checks passed
@killertcell428
killertcell428 deleted the docs/readme-v2-value branch August 24, 2026 10:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant