[programming_examples] llama32_1b: verify subsystem + docs

[tonyjie]

Re-targeted from #1635 onto llama-verify so a maintainer can workflow_dispatch buildAndTestRyzenAI.yml against this branch and exercise HF_TOKEN-gated tests end-to-end before merging to main.

Summary

Builds on the existing programming_examples/llama32_1b/ example (PR #1590 + #1610) with two additions plus CI wiring to run the new verification test:

• Verify subsystem (verify/) — end-to-end HF parity gate that runs the production NPU prefill+decode path and compares per-position logits against the HuggingFace bf16 reference using top-k token inclusion (vLLM-style check_logprobs_close method).
  • make verify — fast CI gate, 2 prompts × 32 greedy tokens, k=5, ~2 min.
  • make verify-full — exhaustive local sweep over the full prompt file (currently 8 prompts), ~6 min.
  • make diagnosis — per-layer ffn_out cosine + max_abs vs HF bf16 for one prompt (informational microscope).
  • Includes production-loop refinements (llama32_1b_{inference,prefill,decode,cpu_helpers}.py, kernel_builder/cache.py, kernel_builder/external_kernels.py) needed to surface intermediates cleanly, plus a profiling redesign (end-to-end dataflow timing, TTFT reporting, per-token trend).
• Standalone docs (docs/detail/) — IMPLEMENTATION_GUIDE.html, VERIFICATION.html, PROFILE.html walkthroughs (HTML kept under docs/detail/ to stay separate from the markdown reference docs). Plus updates to docs/{usage,profile,explain}.md describing the new verify/profile workflows.
• CI wiring — exposes the existing HF_TOKEN repo secret to the check-programming-examples-peano step in .github/workflows/buildAndTestRyzenAI.yml so the new run_npu2_verify.lit (which needs gated meta-llama weights) can authenticate.

Three commits, one per logical area, all confined to programming_examples/llama32_1b/ (+ the hf_token LIT feature in programming_examples/lit.cfg.py and the CI line in .github/workflows/buildAndTestRyzenAI.yml). Also removes docs/issues.md (added by #1590) — its content is either resolved (BF16 RoPE bug now fixed) or covered by the new HTML walkthroughs.

Scope: 33 files, +6522 / −1132.

How to validate before merge

Because PRs from forks can't access repo secrets (GitHub policy), automated CI on this PR skips run_npu2_verify.lit with UNSUPPORTED. To exercise it for real:

1. Merge this PR into Xilinx:llama-verify (or otherwise land its commits there).
2. Trigger workflow_dispatch on Build and Test with AIE tools on Ryzen AI against the llama-verify branch directly (the branch, not the PR). That run has full secret access.
3. Confirm in the lit output:
   • HF_TOKEN found in environment; hf_token feature enabled.
   • PASS: AIR_TEST :: programming_examples/llama32_1b/run_npu2_verify.lit
4. Once green on llama-verify, fast-forward into main.

hf_token LIT feature

run_npu2_verify.lit requires gated meta-llama/Llama-3.2-1B weights, so it carries REQUIRES: ryzen_ai_npu2, peano, hf_token. The feature is registered in programming_examples/lit.cfg.py (~lines 128–135) and only available when HF_TOKEN is set in the environment. Tests skip cleanly with UNSUPPORTED when it's unset.

Rendered docs preview

The three HTML walkthroughs render in-browser via raw.githack.com (a free GitHub-content proxy):

• IMPLEMENTATION_GUIDE.html — model architecture, per-kernel building blocks, NPU mapping
• VERIFICATION.html — HF parity gate methodology and results
• PROFILE.html — end-to-end dataflow and per-step timing

If you'd prefer these published to the official Pages site (xilinx.github.io/mlir-air/), happy to follow up with a small change to .github/workflows/generateDocs.yml to copy them into the publish directory — kept out of this PR so it can be reviewed separately.

Test plan

• 3 representative XRT tests pass under flock /tmp/mlir-air-npu.lock on NPU2 (02_mul_shim_1x1, 06_add_shim_bf16, 12_matmul_transform_1x4_bf16)
• make compile succeeds end-to-end on programming_examples/llama32_1b/ against latest upstream/main toolchain
• make verify PASS 2/2 prompts on NPU2 against real meta-llama/Llama-3.2-1B-Instruct weights (top-k inclusion, k=5)
• make run (N_TOKENS=5): TTFT 1.41 s, 10.6 tok/s, sensible output
• make profile (N_TOKENS=3): all 5 redesigned profiling sections (Wall-Time Attribution, Per-Layer Execution, NPU XRT Call Breakdown, CPU Op Breakdown, Fine-Grained NPU Breakdown) + END-TO-END DATAFLOW
• make diagnosis: per-layer probe across 16 layers, report written
• CI side: pending maintainer workflow_dispatch against llama-verify to validate secret wiring end-to-end

Supersedes #1635.