docs: expand flowise and logseq advanced chapters (#58)

Author: johnxie

tutorials/flowise-llm-orchestration/06-security-governance.md

@@ -8,23 +8,50 @@ parent: "Flowise LLM Orchestration"
 
 # Chapter 6: Security and Governance
 
-Security controls are required when orchestrating models, tools, and external data.
+Flowise workflows combine models, tools, connectors, and credentials. Governance must be explicit.
 
-## Core Risk Areas
+## Primary Risk Areas
 
-- secret leakage in node configs and logs
-- unsafe tool execution with unvalidated model output
-- data exfiltration via connectors
+- secrets exposed in node configs or logs
+- unsafe tool execution from unvalidated model outputs
+- data exfiltration through permissive connectors
+- tenant boundary violations in shared deployments
 
-## Governance Controls
+## Security Control Layers
 
-- scoped credentials per workflow/environment
-- allowlisted tools and outbound domains
-- policy checks for prompt and response classes
-- immutable audit logs for workflow runs
+| Layer | Required Control |
+|:------|:-----------------|
+| Credential handling | scoped secrets per environment/workflow |
+| Tool invocation | input validation + allowlists |
+| Data access | least privilege for connectors and stores |
+| Network egress | outbound domain and protocol restrictions |
+| Audit | immutable run-level logs with redaction |
+
+## Governance Process
+
+1. classify workflow risk level (read-only vs mutating)
+2. require reviews for prompt/node changes on high-risk flows
+3. version workflow definitions and policies together
+4. enforce release gates before production promotion
+
+## Runtime Safeguards
+
+- timeout budgets per node
+- bounded retry policies
+- explicit human approval for destructive actions
+- deny-by-default for new external tool integrations
+
+## Incident Readiness
+
+Maintain playbooks for:
+
+- secret leakage response
+- unsafe automation rollback
+- connector compromise or abuse
+- tenant-isolation incidents
 
 ## Summary
 
-You now understand baseline security posture for Flowise workflow operations.
+You now have a practical security and governance baseline for operating Flowise in production.
 
 Next: [Chapter 7: Observability](07-observability.md)

tutorials/flowise-llm-orchestration/07-observability.md

@@ -8,23 +8,47 @@ parent: "Flowise LLM Orchestration"
 
 # Chapter 7: Observability
 
-Observability converts workflow execution into actionable operational signals.
+Observability turns visual workflow orchestration into measurable production behavior.
 
 ## Metrics Baseline
 
-- workflow run latency (p50/p95/p99)
-- node-level failure rates and retry counts
-- token usage and cost per workflow
-- external dependency error rates
+Track at least:
+
+- workflow latency (p50/p95/p99)
+- node-level error and retry rates
+- model token usage and cost per run
+- connector dependency latency/failure rates
 
 ## Trace Strategy
 
-- assign run IDs to every invocation
-- capture node input/output metadata safely
-- correlate model/tool calls within one trace
+Use a single run ID from entrypoint to final output.
+
+Per node, capture:
+
+- start/end timestamps
+- node type and version
+- safe metadata for inputs/outputs
+- retry and fallback path taken
+
+This allows fast root-cause analysis for partial failures.
+
+## Logging Standards
+
+- redact secrets and sensitive payload fields
+- keep structured logs (JSON) for machine querying
+- include policy decisions (allowed/blocked/escalated)
+
+## Alerting Rules
+
+| Alert | Trigger |
+|:------|:--------|
+| latency regression | p95 exceeds SLO threshold |
+| failure burst | node error rate spike |
+| cost anomaly | run cost deviates from baseline |
+| dependency outage | repeated connector timeout/failures |
 
 ## Summary
 
-You can now instrument Flowise workflows for debugging and performance management.
+You can now instrument Flowise workflows to debug incidents quickly and manage performance/cost predictably.
 
 Next: [Chapter 8: Extension Ecosystem](08-extension-ecosystem.md)

tutorials/flowise-llm-orchestration/08-extension-ecosystem.md

@@ -8,23 +8,40 @@ parent: "Flowise LLM Orchestration"
 
 # Chapter 8: Extension Ecosystem
 
-This chapter covers sustainable extension development and ecosystem growth.
+A sustainable extension ecosystem determines whether Flowise remains adaptable as requirements evolve.
 
 ## Extension Design Principles
 
-- stable input/output contracts for custom nodes
-- semantic versioning for extension APIs
-- compatibility tests across core Flowise versions
+- keep node input/output contracts explicit and versioned
+- isolate side effects behind clear interfaces
+- ship deterministic error semantics
+- document compatibility by Flowise/core dependency versions
+
+## Release and Compatibility Model
+
+1. semantic version extension packages
+2. maintain compatibility matrix per Flowise release line
+3. run extension conformance tests in CI
+4. deprecate old APIs with migration notes and timelines
 
 ## Distribution Patterns
 
-- internal extension catalogs for enterprise teams
-- open-source packages for community reuse
-- review workflows for security and quality gates
+- internal extension catalogs for enterprise governance
+- open-source packages for reusable community nodes
+- signed artifact distribution for high-trust environments
+
+## Quality Gates
+
+| Gate | Purpose |
+|:-----|:--------|
+| schema tests | prevent contract regressions |
+| security review | catch unsafe connector/tool behaviors |
+| performance checks | detect high-latency node paths |
+| docs completeness | ensure operators can support extension |
 
 ## Final Summary
 
-You now have complete Flowise coverage from architecture and execution to secure production and extensibility.
+You now have a blueprint for building and maintaining a robust Flowise extension ecosystem.
 
 Related:
 - [Flowise Index](index.md)

tutorials/logseq-knowledge-management/02-system-architecture.md

@@ -8,29 +8,38 @@ parent: "Logseq Knowledge Management"
 
 # Chapter 2: System Architecture
 
-This chapter maps Logseq's desktop architecture and data flow.
+This chapter maps Logseq's architecture from desktop runtime to graph-level services.
 
-## Architecture Layers
+## Core Architecture Layers
 
-- Electron shell for desktop runtime and native integrations.
-- ClojureScript core for state + domain logic.
-- Datascript + filesystem for local-first persistence.
+- **Desktop shell**: Electron runtime and native integration boundary
+- **Application core**: ClojureScript state, commands, and domain logic
+- **Persistence/index**: plain-text files plus in-memory/query index
+- **UI layer**: block editor, page views, graph view, search surfaces
 
-## Data Flow
+## Data Flow Model
 
 ```text
-user action -> event handler -> state update -> markdown write/sync
+user action -> command/event -> state transition -> file sync/index update -> UI re-render
 ```
 
-## Core Modules
+## Module Responsibilities
 
-- parser and block index
-- page/link graph manager
-- search and query execution
-- plugin runtime bridge
+| Module | Responsibility |
+|:-------|:---------------|
+| parser | convert markdown/org into block structures |
+| block graph manager | maintain parent/child and reference edges |
+| query engine | execute page/block graph queries |
+| plugin bridge | expose extension hooks safely |
+
+## Architectural Tradeoffs
+
+- local-first responsiveness vs cross-device consistency complexity
+- plain-text durability vs richer schema constraints
+- extensibility power vs plugin isolation/security overhead
 
 ## Summary
 
-You can now identify where Logseq responsibilities are split across runtime layers.
+You can now reason about where Logseq behavior originates and where to debug architectural issues.
 
 Next: [Chapter 3: Local-First Data](03-local-first-data.md)

tutorials/logseq-knowledge-management/03-local-first-data.md

@@ -8,22 +8,39 @@ parent: "Logseq Knowledge Management"
 
 # Chapter 3: Local-First Data
 
-Logseq's local-first model combines plain-text files with indexed graph state.
+Logseq's local-first model centers on user-owned files with graph indexing layered on top.
 
 ## Storage Principles
 
-- Markdown/Org files remain user-owned source of truth.
-- Datascript index accelerates query and traversal.
-- Sync is optional, not required for core app behavior.
+- markdown/org files are canonical source of truth
+- index/cache layers accelerate queries and backlinks
+- core workflows remain usable offline
 
-## Integrity Practices
+## Consistency Model
 
-- Use deterministic block IDs.
-- Rebuild index from files on corruption recovery.
-- Keep file writes atomic for crash safety.
+In practice, systems must reconcile:
+
+1. file-system truth
+2. in-memory graph state
+3. rendered UI state
+
+Robust implementations include deterministic reload/index rebuild paths when state diverges.
+
+## Durability and Recovery
+
+- atomic file writes where possible
+- deterministic block IDs for stable references
+- index rebuild tools for corruption scenarios
+- clear conflict resolution strategy for sync setups
+
+## Local-First Benefits
+
+- data portability and longevity
+- lower dependence on hosted services
+- predictable offline behavior
 
 ## Summary
 
-You can now reason about Logseq's local durability and synchronization tradeoffs.
+You can now evaluate local-first tradeoffs and design recovery pathways that protect data integrity.
 
 Next: [Chapter 4: Development Setup](04-development-setup.md)

tutorials/logseq-knowledge-management/05-block-data-model.md

@@ -8,24 +8,43 @@ parent: "Logseq Knowledge Management"
 
 # Chapter 5: Block Data Model
 
-Blocks are Logseq's atomic knowledge units.
+Blocks are the atomic units of content and graph connectivity in Logseq.
 
-## Block Fields
+## Block Structure
 
-- stable UUID
-- text/content payload
-- parent-child hierarchy
-- page and backlink relationships
-- metadata (timestamps, properties, tags)
+A robust block model typically includes:
 
-## Model Constraints
+- stable UUID/ID
+- textual content
+- parent-child ordering metadata
+- page association
+- references/tags/properties
+- creation/update metadata
 
-- parent references must remain acyclic
-- order indexes must be deterministic
-- link refs must survive text edits
+## Invariants
+
+- hierarchy must remain acyclic
+- sibling order must be deterministic
+- references should survive text edits and reformatting
+- deleted/moved blocks should not leave dangling graph edges
+
+## Mutation Types
+
+1. content edit
+2. reorder/reparent
+3. reference/property change
+4. delete/restore
+
+Each mutation should update both hierarchy and graph indexes consistently.
+
+## Validation Practices
+
+- schema validation before persisting
+- invariant checks in development/test mode
+- repair routines for broken references
 
 ## Summary
 
-You can now map user edits to the underlying block graph model.
+You can now map user operations to block-level graph mutations and identify where consistency bugs emerge.
 
 Next: [Chapter 6: Block Editor](06-block-editor.md)

tutorials/logseq-knowledge-management/06-block-editor.md

@@ -8,23 +8,39 @@ parent: "Logseq Knowledge Management"
 
 # Chapter 6: Block Editor
 
-The Logseq editor handles hierarchical editing and reference-centric workflows.
+The block editor is where text editing, structural hierarchy, and graph references converge.
 
-## Core Behaviors
+## Core Interaction Model
 
-- indentation controls parent-child structure
-- slash commands drive structured inserts
-- reference syntax creates graph edges inline
-- keyboard-first navigation optimizes flow
+- indentation/outdent controls hierarchy
+- inline references create graph edges
+- keyboard-first commands optimize authoring speed
+- slash commands trigger structured actions/templates
 
-## Reliability Concerns
+## Engineering Challenges
 
-- selection consistency across nested edits
-- undo/redo across structure + text changes
-- low-latency edits on large page trees
+| Challenge | Why It Is Hard |
+|:----------|:---------------|
+| nested selection behavior | text + structure edits overlap |
+| undo/redo correctness | must restore both text and tree shape |
+| low-latency updates | large pages can trigger heavy recalculation |
+| IME/multilingual editing | composition events complicate key handling |
+
+## Reliability Patterns
+
+- incremental state updates for large documents
+- deterministic edit transactions
+- robust cursor restoration after structural edits
+- regression tests for keyboard workflows
+
+## UX Quality Signals
+
+- predictable tab/shift-tab behavior
+- no cursor jumps during auto-formatting
+- stable performance in deeply nested pages
 
 ## Summary
 
-You can now analyze editor behavior as structured graph mutations.
+You can now analyze editor behavior as transaction-safe graph and text mutations.
 
 Next: [Chapter 7: Bi-Directional Links](07-bidirectional-links.md)