docs: add safe-output permissions reference and TF401027 troubleshooting guide

[jamesadevine]

Summary

Adds a dedicated reference for the most common Stage 3 runtime
failure: 401/403 on safe outputs because $(System.AccessToken)
resolves to a build-service identity (Project Collection Build
Service or per-project Build Service) that lacks
PullRequestContribute / GenericContribute / CreateBranch on
the target repo — sometimes via an explicit Deny, which can't
be defeated by group-level Allow.

This grew out of a real failed run where the agent produced 8 valid
add-pr-comment proposals and every one came back from ADO with:

TF401027: You need the Git 'PullRequestContribute' permission to
perform this action. Details: identity 'Build\<guid>', scope 'repository'.

There was nothing in the docs that explained which identity that
Build\<guid> actually is, that the project-level "Limit job
authorization scope to current project" toggle is what flips
$(System.AccessToken) between the collection-scoped and
project-scoped build services, or how to read the permission
bitmasks the Security REST API returns. This PR fixes that.

What's new

• docs/safe-output-permissions.md — repo-level reference,
  linked from the AGENTS.md docs index next to safe-outputs.md.
• site/src/content/docs/troubleshooting/safe-output-permissions.mdx
  — site mirror. Auto-included in the sidebar via the
  troubleshooting/ autogenerate config.

What's updated

• AGENTS.md — new bullet in the "Authoring agent files" docs
  index pointing at the reference page.
• site/.../troubleshooting/common-issues.mdx — new
  "Stage 3 SafeOutputs fails with HTTP 403 / TF401027" entry that
  cross-links the dedicated page.
• site/.../setup/service-connections.mdx — new row in the
  troubleshooting table for the same-project TF401027 … PullRequestContribute case (the existing row only covered the
  cross-project variant).
• prompts/debug-ado-agentic-workflow.md — Stage 3 "Write
  Token Issues" section rewritten with the TF401027 decoder
  table, Build\<guid> → identity mapping, an explicit-Deny-wins
  note, and a pointer to the new reference. Teaches the debug
  agent to dump the right diagnostic detail when filing issues for
  this failure class.

Content covered (consistently across all entry points)

Topic	Where
TF401027 error format & how to read <PermissionName> / Build\<guid> / <scope>	reference doc, site page, debug prompt
Default $(System.AccessToken) → PCBS vs project-scoped Build Service mapping	reference doc, site page, debug prompt
"Limit job authorization scope to current project" toggle (per-pipeline / project / org)	reference doc, site page
Cross-project caveat (sibling-project repos, pipeline artifacts, secure files, template extends:)	reference doc, site page
Git Repositories permission bitmask decoder	reference doc, site page
Which safe-output tool needs which permission bit	reference doc, site page
az + REST recipe to dump the ACL for any identity on any repo	reference doc, site page
Three fix paths (write SC / flip toggle / lift Deny), recommended order, blast-radius notes	reference doc, site page, debug prompt
Common 401/403 signatures table (TF400813, TF401027, VS800075, TF401019, silent 404)	reference doc, site page

Test plan

• Site build — cd site && npm run build:
  • Builds clean (35 pages, including the new
    /troubleshooting/safe-output-permissions/).
  • starlight-links-validator reports "All internal links are
    valid."
• Manual cross-reference check — verified every internal link
  in the two new files (docs/safe-output-permissions.md →
  safe-outputs.md, network.md, audit.md; site page →
  /ado-aw/setup/service-connections/, /ado-aw/reference/safe-outputs/,
  /ado-aw/reference/audit/) resolves.
• Bitmask table sourced from live API — the Git Repositories
  permission table in both new files was generated by querying
  securitynamespaces/2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87 against
  a live ADO org and ordered by bit value, so the bit/name/display-name
  triples match what the ADO REST API actually returns today.
• REST recipe verified end-to-end — the az + curl snippets
  in the reference page are the exact commands used during the
  investigation that motivated this PR; they produced the example
  effectiveDeny: 16404 response quoted in the doc.

No code changes — docs and prompt content only. No compiler / tool
behavior changes.