Skip to content

Improve Architecture and Tutorials navigation - #338

Merged
cdcavell merged 172 commits into
mainfrom
issue_work
Sep 14, 2026
Merged

cdcavell merged 172 commits into
mainfrom
issue_work

Conversation

@cdcavell

Copy link
Copy Markdown
Contributor

Summary

Optimizes the Architecture and Tutorials landing pages to improve scanability, navigation, and progression through ASI Backbone Learning while preserving the existing DocFX-compatible Markdown structure and destination links.

The changes are intentionally focused on two pages that had accumulated the most explanatory density:

  • docs/architecture/index.md
  • docs/tutorials/index.md

Changes

Architecture

  • Added a Start by Question table to help readers enter the architecture material based on what they are trying to understand.
  • Moved the recurring governed-execution boundary closer to the top of the page.
  • Reframed the core flow around six practical architectural questions:
    • Who proposes the operation?
    • Which facts influence the decision?
    • Where is policy evaluated?
    • What authority exists after approval?
    • Which component performs the side effect?
    • What evidence remains afterward?
  • Consolidated architectural status guidance into a more compact Pattern Classifications section.
  • Converted foundational organization concepts into a concise reference table.
  • Added a clearer Foundational Learning Path section linking directly to the five core tutorials.
  • Reworked the large alternative-pattern list into a Compare Adjacent Architectures table organized around the decision each comparison helps answer.
  • Preserved working-repository references and all existing destination links.

Tutorials

  • Added a compact Learning Path at a Glance table showing:
    • tutorial order
    • difficulty
    • the architectural boundary introduced at each step
  • Consolidated the explanation of the problem-first tutorial model.
  • Combined Pattern Card and Check Your Understanding guidance into a clearer How a Tutorial Works section.
  • Reorganized the five foundational tutorials around their core architectural purpose rather than long topic inventories.
  • Preserved the complete governed AI execution flow.
  • Strengthened the transition from:
    • Tutorial
    • Executable Sample
    • Hands-On Lab
    • Working Repository
  • Reinforced that the curriculum is intended to be questioned, simplified, adapted, or rejected when another design better fits the problem.

Design Goals

  • Reduce cognitive load on section landing pages.
  • Make first-entry decisions easier for new readers.
  • Preserve the problem-first learning model.
  • Keep simpler architectural alternatives visible.
  • Improve progression from conceptual material into runnable evidence and hands-on practice.
  • Preserve all existing DocFX-compatible links and navigation behavior.

Validation

  • All existing Architecture links were preserved.
  • All existing Tutorials links were preserved.
  • git apply --check passed.
  • git diff --check passed.
  • Only the following files were modified:
    • docs/architecture/index.md
    • docs/tutorials/index.md

cdcavell and others added 28 commits September 6, 2026 11:00
Adds docs/articles/2026/your-audit-log-is-not-evidence.md, a standalone
article arguing that a log line written after an operation narrates an
outcome rather than establishing what was decided.

The article works through four failures: the record captures the outcome
instead of the decision and its inputs, nothing binds the record to the
operation it describes, the record is written after the protected effect,
and integrity ends at whatever the log sink provides. It closes with
record-focused tests, explicit guidance on when an ordinary structured log
is the right answer, and a review checklist.

Registers the article in docs/articles/toc.yml and docs/articles/index.md
following the existing newest-first ordering and permanent year/slug URL
convention.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Enable and document the desired repository security posture for Learning,
including Dependabot security updates, secret scanning, push protection,
and an explicit main-branch ruleset.

Preserve required documentation, link, sample, and CodeQL checks while
requiring squash-only linear history, stale-review dismissal, resolved
review threads, and a pull-request-only emergency bypass.

Closes #287
@cdcavell
cdcavell merged commit 0dd0910 into main Sep 14, 2026
11 checks passed
@cdcavell
cdcavell deleted the issue_work branch September 14, 2026 14:00
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