optimize redme

docs/guides/assets/casan-agentic-runtime.mmd

@@ -0,0 +1,26 @@
+flowchart TB
+  U["Developer"] --> C1["Claude Code"]
+  U --> C2["Codex"]
+  U --> C3["VS Code: @casan"]
+
+  C1 --> E1["Project hook events"]
+  C2 --> E1
+  C3 --> E2["CASAN-owned VSIX route"]
+
+  E1 --> B[".casan/casan-hook.py"]
+  E2 --> B
+  B --> V{"Global harness<br/>matches version.lock?"}
+  V -- "No" --> D["Deny or degrade<br/>according to mode"]
+  V -- "Yes" --> A["Client adapter"]
+  A --> G["Agentic bridge"]
+
+  subgraph TURN["Per-turn lifecycle"]
+    direction LR
+    L1["Admission<br/>H1 + H4"] --> L2["Pre-tool gate<br/>H2 + H4"]
+    L2 --> L3["Post-tool evidence<br/>H5"]
+    L3 --> L4["Finalize<br/>H3 + H5 + H6 + H7"]
+  end
+
+  G --> L1
+  L4 --> S["Project runtime state<br/>.specify/logs + state"]
+  L4 --> R["Native client result"]

docs/guides/assets/casan-hybrid-layout.mmd

@@ -0,0 +1,35 @@
+flowchart TB
+  subgraph M["Developer machine"]
+    H["CASAN_HOME"]
+    CUR["current<br/>symlink hoặc junction"]
+    VER["versions/&lt;version&gt;"]
+    CLI["bin/casan"]
+    HAR["packages/casan-harness"]
+    DEV["packages/casan-devkit"]
+
+    H --> CUR --> VER
+    H --> CLI
+    VER --> HAR
+    VER --> DEV
+  end
+
+  INIT["casan init"] --> CFG
+  CLI --> INIT
+  DEV --> INIT
+
+  subgraph P["Existing project"]
+    CFG[".casan/<br/>config.json<br/>version.lock<br/>agentic.env<br/>init-manifest.json"]
+    BOOT[".casan/casan-hook.py"]
+    STATE[".specify/<br/>logs/<br/>state/<br/>.gitignore"]
+    CLIENTS["Client config khi được chọn<br/>.claude/settings.json<br/>.codex/hooks.json<br/>.vscode/extensions.json"]
+    L2["Level 2 only<br/>.gitea/workflows/casan-ci.yml<br/>apps/&lt;project-id&gt;/domain/"]
+    OWNED["Project-owned<br/>source, agents, skills,<br/>commands, hooks và CI khác"]
+  end
+
+  INIT --> BOOT
+  INIT --> STATE
+  INIT --> CLIENTS
+  INIT -. "chỉ khi --level devkit" .-> L2
+  INIT -. "không thay đổi" .-> OWNED
+  CFG --> BOOT
+  HAR -. "runtime policy" .-> BOOT