Minthigpen/docs readme updates

[minthigpen]

PR Summary

Overview

This PR delivers a user-facing docs and examples cleanup focused on command consistency, onboarding clarity, and terminology alignment.

Scope

• Branch is 6 commits ahead of main.
• Net diff: 22 files changed, 202 insertions, 91 deletions.
• Primary areas: docs navigation/content polish, examples command fixes, incident-triage terminology updates, and a small

Updated todo list

website/docs wording refresh.

What Changed

• Unified CLI usage in examples by correcting legacy command references:

  • README.md
  • README.md

• Fixed science research env var typo to match runtime behavior:

  • README.md

• Updated incident-triage example wording from AgentShield to AgentControlSpecification across docs/config/comments and notebook text:

  • README.md
  • agent_guarded.py
  • eval_config_baseline.yaml
  • eval_config_guarded.yaml
  • eval_config_guarded_gepa.yaml
  • eval_config_naive_prompt.yaml
  • incident-triage.guardrails.yaml
  • optimize_with_gepa.ipynb

• Refined docs landing and orientation pages for clearer quickstart/discovery:

  • README.md
  • getting-started.md
  • overview.md
  • create-evaluation.md
  • AGENTS.md

• Minor migration/terminal wording updates:

  • design-migration.md
  • Terminal.tsx

Commit Highlights

• 97ab7a9 docs/examples: fix CLI typo + env var typo and rename AgentControlSpecification refs
• 6426db6 clean up of migration terminology and doc updates
• c1e5835 docs: refine docs index and migration wording
• 95b758c docs: rename CLI/python refs and clean user-facing wording
• 91d5ed0 docs: refine docs index and migration wording
• 6498ff6 docs: rename CLI/python refs and clean user-facing wording

Validation Notes

• No remaining matches for the two concrete regressions in examples:
  • legacy assert-eval run/status lines
  • ASSERT_AI_REAL_TOOLS_NOCACH typo
• Remaining AgentShield mentions are confined to generated artifacts under incident-triage results (left intentionally unchanged).

[Copilot]

Pull request overview

This PR updates user-facing documentation and examples to improve onboarding clarity, unify CLI command usage, and align incident-triage terminology from “AgentShield” to “AgentControlSpecification”.

Changes:

• Refines docs navigation/wording (docs landing pages, getting started, CLI overview, migration brief, agent orientation).
• Updates incident-triage example text/configs/prompts/notebook to use AgentControlSpecification terminology and links.
• Adjusts example CLI/model strings and small UI copy (Terminal title default).

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
website/docs/design-migration.md	Primer-style design brief formatting/wording cleanup and terminology update.
website/app/Terminal.tsx	Changes default terminal title string.
examples/science_research_agent/README.md	Updates “how to run” instructions (needs de-dup).
examples/README.md	Updates example overview text and model string guidance (needs model consistency).
examples/incident_triage_agent/SOP.md	Replaces AgentShield mentions with AgentControlSpecification link/text.
examples/incident_triage_agent/README.md	Broad terminology/link update (plus a grammar fix and prereq clarification needed).
examples/incident_triage_agent/prompts/xpia_paraphrase.md	Updates vendoring note wording.
examples/incident_triage_agent/prompts/cross/pii_detection.md	Updates upstream vendoring reference string.
examples/incident_triage_agent/optimize_with_gepa.ipynb	Updates terminology inside notebook markdown.
examples/incident_triage_agent/incident-triage.guardrails.yaml	Updates inline commentary to new terminology.
examples/incident_triage_agent/eval_config_naive_prompt.yaml	Updates header/comment terminology.
examples/incident_triage_agent/eval_config_guarded.yaml	Updates header/comment terminology.
examples/incident_triage_agent/eval_config_guarded_gepa.yaml	Updates header/comment terminology.
examples/incident_triage_agent/eval_config_baseline.yaml	Updates header/comment terminology.
examples/incident_triage_agent/agent.py	Updates docstring terminology reference.
examples/incident_triage_agent/agent_guarded.py	Updates terminology in docstrings/log/error strings (needs consistency with agent_shield implementation + error-code casing).
eval_config.yaml	Adds a new root-level config file (needs alignment with onboarding/docs or relocation/removal).
docs/README.md	Reworks docs index and adds install snippet (needs correct package name + code fence language).
docs/guides/create-evaluation.md	Updates init model string and adds guidance (needs de-dup).
docs/getting-started.md	Adds/updates quickstart copy (contains multiple duplicated lines/blocks).
docs/cli/overview.md	Updates init model string and examples (contains multiple duplicated lines).
AGENTS.md	Updates model string and adds terminology note (contains multiple duplicated lines/steps/bullets).

Comments suppressed due to low confidence (15)

docs/getting-started.md:51

• Duplicate command line in the quickstart run block.

assert-ai run --config examples/travel_planner_langgraph/eval_config.yaml

**docs/getting-started.md:58**
* Duplicate command line in the results-status block.

docs/getting-started.md:72

• The Codespaces / Dev Container paragraph is duplicated, likely from a merge conflict.

Windows PowerShell equivalent:

docs/getting-started.md:87

• The Windows PowerShell example repeats the same run/status commands twice.

1. `systematize` expanded the behavior spec into behavior categories.

docs/cli/overview.md:7

• The CLI overview shows the canonical command twice in the same code block.

assert-ai

**docs/cli/overview.md:24**
* Duplicate command line in the workflow example.

docs/cli/overview.md:31

• Duplicate command line in the workflow example.

1. Compare runs:

docs/cli/overview.md:38

• Duplicate command line in the workflow example.

## Command groups

docs/getting-started.md:87

• The Windows PowerShell example repeats the same run/status commands twice; remove the duplicated pair to avoid confusing copy/paste.

## What just happened

1. `systematize` expanded the behavior spec into behavior categories.

docs/guides/create-evaluation.md:77

• This line is duplicated, likely from an edit/merge artifact.

Use `assert-ai init` or manual YAML editing to create evaluations.

examples/science_research_agent/README.md:54

• The run command is duplicated; keep a single line so copy/paste works as expected.

assert-ai run --config examples/science_research_agent/eval_config.yaml

**AGENTS.md:63**
* This paragraph is duplicated.

Terminology divergence to know about: in customer-facing docs we call target.model + target.tools the Prompt Agent target (the agent is declared in YAML; the runtime owns the tool-call loop). In code, the corresponding session class is HostedSession (assert_ai/core/session.py). Use the customer-facing name in docs and the class name in code references — this divergence is intentional and not worth renaming.

**AGENTS.md:84**
* Duplicate command in the bash setup snippet.

AGENTS.md:100

• Duplicate command in the PowerShell setup snippet.

## How to help with common tasks

AGENTS.md:115

• Step 9 duplicates step 8; keep a single instruction to run the pipeline.

Read artifacts in this order: