Skip to content

docs(readme): easy diagrams — what AAP is for and how it works - #4

Merged
gitpash merged 4 commits into
mainfrom
docs/readme-diagrams-grasp
Oct 16, 2026
Merged

gitpash merged 4 commits into
mainfrom
docs/readme-diagrams-grasp

Conversation

@gitpash

@gitpash gitpash commented Oct 16, 2026

Copy link
Copy Markdown
Owner

Summary

  • Rewrite README lead-in for 0.2.1-prototype graspability
  • Mermaid: without/with AAP, L0–L3 disclosure, hub hops, optional profiles, Core vs profile, upstream pin
  • Keep Core small / profiles optional fences

Not

  • Schema or version bump

Refresh top-of-README for graspability: failure modes, Core flow,
progressive disclosure, hub hops, optional profiles, pin story.
Mermaid diagrams; keep Core vs profile fence explicit.
- Honest without-map path (AGENTS/wiki/grep); AAP vs AGENTS one-liner
- L0–L3: optional L2; profile side branch not between L0/L1
- Profiles: work then done-bar at exit
- Core vs profile: envelope conditional; no ambiguous promote arrow
- Problem table: fake confidence = done-bar profile
- self.parent in map sample + vocabulary (schema-backed)
- Reorder: Core → 60s start → hub → profiles; drop pin diagram
- Soften bet; link MOTIVATION; slim status/header
@gitpash

gitpash commented Oct 16, 2026

Copy link
Copy Markdown
Owner Author

Addressed review on the branch:

  1. Core vs profile diagram — envelope in conditional subgraph; removed promote arrow
  2. L0–L3 — profile side-only; L2 optional dashed
  3. Profiles — `S → W → D` (done-bar at exit)
  4. Problem table — Fake confidence → Profile (done-bar) + Addressed-by column
  5. `self.parent` — schema-backed; in sample map + vocabulary
  6. Fewer diagrams; pin = one sentence under clone
  7. Section order: problem → Core → 60s → hub → profiles → Core vs profile
  8. AGENTS.md relationship one-liner; softer bet + MOTIVATION link

Please re-check Mermaid preview on GitHub.

- Define access (path fence) vs write (node role hints) from schema/SPEC
- Status: docs + schema + validator; drop orphan mutating-mode line
- L0–L3: L0 -.-> optional profile; hub: child -.->|self.parent| hub
- Core vs profile: node ~~~ links (C2/C3/P1)
- A/B labels; pin comment in map copy snippet
- Topology wording; drop duplicate upstream table; init → CONTRIBUTING link
@gitpash

gitpash commented Oct 16, 2026

Copy link
Copy Markdown
Owner Author

Second review pass — all items addressed on branch:

  1. `access` vs `write` — both schema-backed; table + sample map + vocabulary
  2. Default posture — linked to SPEC; no unexplained “mutating mode” orphan
  3. `self.parent` — confirmed pre-existing on `v0.2.1-prototype` schema (not a schema bump)
  4. Status — “docs + schema + validator”
    5–7. Diagrams — node `~~~`, `L0 -.-> P`, hub `self.parent` reverse dashes
  5. A/B named in step 4
  6. Pin kept as `# aap-pin:` comments in copied map
  7. Init tooling → CONTRIBUTING link only
  8. Topology: “direct hops; paths meant to resolve”
  9. Dropped duplicate “Upstream vs your repo” section (folded into Status + 60s)

Please re-check Mermaid preview, then merge if happy.

- Sample map validated against map.schema.json (string+list+write[])
- Status: optional fields pre-exist; not “required fields unchanged”
- access/write defined once in §1; vocab + Core-vs-profile link back
- write-home one line + SPEC pointer
- Default posture: runtime recommendation, not Core MUST
- L0 diagram label: optional profile only
- Confirm v0.2.1-prototype has minimal-map template
@gitpash

gitpash commented Oct 16, 2026

Copy link
Copy Markdown
Owner Author

Third pass — remaining review items:

  1. Sample map — validated with `jsonschema` against `schemas/map.schema.json` (string layout + list artifacts + `write: [domain]` OK)
  2. Status — reworded: schema unchanged; `self.parent` / `access` / node `write` already optional in Map v2 (not “required fields”)
  3. Tag — `v0.2.1-prototype` exists; `templates/minimal-map.yaml` present on tag
  4. access/write — canonical only in How-it-works §1; Vocabulary + Core-vs-profile link there
  5. write-home — one sentence + SPEC link (not a free-floating term dump)
  6. Default posture — explicitly runtime recommendation, not Core MUST
  7. L0 edge label — `optional profile` only

Ready to merge pending Mermaid preview.

@gitpash
gitpash merged commit 610c9ec into main Oct 16, 2026
1 check passed
@gitpash
gitpash deleted the docs/readme-diagrams-grasp branch October 16, 2026 09:49
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