feat: KnowledgeFS and New Knowledge

.agents/skills/frontend-code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontend-code-review
-description: Use only when the user explicitly requests a review or audit of frontend code under `web/` or `packages/dify-ui/`. Supports pending-change, file-focused, and pasted-diff reviews. Do not use for implementation-only requests, diagnosis without review intent, or backend-only code.
+description: Use only when the user explicitly requests a bug, regression, correctness, security, accessibility, performance, or test-quality review of frontend code under `web/` or `packages/dify-ui/`. Supports pending-change, file-focused, and pasted-diff reviews. Do not use for architecture-oriented evaluation of component ownership, state graphs, props, boundaries, or refactoring design unless concrete defects are also requested; do not use for implementation-only requests, diagnosis without review intent, or backend-only code.
 ---
 
 # Frontend Code Review
@@ -11,8 +11,9 @@ Review the requested scope for concrete defects and violations of explicit proje
 
 1. Establish the review scope from the requested files or current diff.
 2. Read the changed lines, their behavior owner, and the nearest scoped `AGENTS.md`.
-3. Trace public consumers, generated contracts, primitive APIs, or runtime configuration only when they decide correctness.
-4. Report findings tied to an observable failure, violated contract, security boundary, or demonstrated maintenance risk. Explicit team conventions are contracts: establish their scope and exceptions, and do not invent user impact to justify a convention finding.
+3. For a named component or a diff that changes component ownership, props, or state, read the component-architecture rule pack and complete its Root-To-Leaf State And Props Audit before drawing conclusions.
+4. Trace other public consumers, generated contracts, primitive APIs, or runtime configuration only when they decide correctness.
+5. Report findings tied to an observable failure, violated contract, security boundary, or demonstrated maintenance risk. Explicit team conventions are contracts: establish their scope and exceptions, and do not invent user impact to justify a convention finding.
 
 ## Rule Routing
 

.agents/skills/frontend-code-review/references/component-architecture.md

@@ -9,6 +9,19 @@ Use the canonical reference for the changed concern. These links share rules; th
 | Effects, navigation, memoization, and subscriptions | [Runtime] |
 | Hotkeys, focus, and secondary surfaces | [Interactions] |
 
+## Root-To-Leaf State And Props Audit
+
+For a file-focused component review, use the named component as the root. For a pending diff, use each changed page, feature entrypoint, or nearest behavior owner whose state or props contract changed.
+
+1. Build the locally owned rendered component tree from each root to every leaf. Follow imported feature components, conditional branches, lists, portals, dialogs, drawers, and popovers. Stop at third-party or Dify UI primitives and explicit stable public feature boundaries, but record the props passed across that final edge.
+2. At every component, inventory state sources: React state/reducers, form state, URL state, context/store/Jotai reads and writes, queries, mutations, refs that hold workflow state, and custom-hook results.
+3. For every state value, derived fact, and handler, record its consuming branches and required lifetime, including persistence across descendant unmounts. Assess its placement against [Ownership] and [State], including their coordination and persistence exceptions.
+4. Inspect every props edge. Mark values that are read by the child, forwarded unchanged, renamed, recomputed, mirrored into local state, or paired with lifecycle fields such as `data/pending/error/retry` and `open/onOpenChange`.
+5. Trace what each forwarding parent actually owns before reporting an unnecessary intermediary. Apply [Ownership] to distinguish required coordination or persistence from merely redistributing workflow fields, and [State] to determine whether a feature graph is warranted.
+6. Remove unused or redundant props at their source. Do not accept replacing many props with a props bag, context, or hook result unless that abstraction becomes the real owner and gives consumers a narrower contract.
+
+Review the complete paths before concluding that a state or prop is necessary. When several edges share one ownership defect, report one finding at the highest incorrect owner and include a representative path such as `Root -> Section -> Leaf`; do not emit a duplicate finding for every child.
+
 ## Apply Rules In Their Actual Scope
 
 Explicit team conventions are reviewable contracts, including module organization and public API boundaries. Check the documented exception before reporting a violation. Do not infer an exception solely because the code appears to work, or invent a user-facing failure for a convention finding.

.agents/skills/how-to-write-component/SKILL.md

@@ -1,24 +1,59 @@
 ---
 name: how-to-write-component
-description: Use when implementing or refactoring React/TypeScript components and the task requires decisions about component ownership, feature boundaries, state, data flow, effects, or interaction ownership. Do not use for review-only requests, test-only work, copy-only edits, or styling-only changes.
+description: Use when implementing, refactoring, or architecture-reviewing React/TypeScript components whose ownership, state lifetimes, data flow, props, feature boundaries, effects, or interaction surfaces need redesign. Do not use for bug, regression, security, or accessibility audits; test-only work; copy-only edits; or styling-only changes.
 ---
 
-# How To Write A Component
+# React Component Architecture
 
-Use this skill to route component architecture decisions to its bundled references. Read only the references required by the current change.
+Use this skill to make component ownership and lifecycle explicit before implementation. Classify every stateful value on three independent dimensions:
+
+1. **Owner/source:** a component, parent boundary, URL/framework API, TanStack Query, or feature workflow.
+2. **Graph role:** primitive input, query/mutation node, derived business fact, or workflow command.
+3. **Lifecycle:** instance isolation, persistence, and reset requirements.
+
+Do not force one label to answer all three dimensions.
+
+Keep display state, submit-only fields, and owner-local queries or mutations with the component or DOM that owns their complete lifecycle. A value enters the feature state graph only when it crosses an ownership boundary, participates in shared derivation or coordination, or must outlive/reset independently of its current owner. Driving an owner-local query or command alone is not sufficient. In this repository, use feature-local Jotai as the default representation once a value enters that graph.
+
+## Operating Modes
+
+Choose the mode from the user's requested outcome:
+
+- **Architecture audit:** Perform a read-only, root-to-leaf analysis and propose the target ownership model. Read [`references/audit.md`][audit] and [`references/ownership.md`][ownership].
+- **Refactoring design:** Perform the architecture audit, then provide target contracts, migration slices, and a verification strategy without modifying code. Read [`references/audit.md`][audit] and [`references/ownership.md`][ownership].
+- **Implementation:** Establish the affected owner map, state graph, props edges, and reset boundaries before editing. Implement one coherent vertical slice at a time, then run the final audit in [`references/audit.md`][audit]. Read [`references/ownership.md`][ownership].
+- **Bug or regression review:** Use the frontend code-review workflow unless the user explicitly requests this skill's architecture model as an additional lens.
 
 ## Topic Routing
 
+After selecting the operating mode, read only the topic references required by the change:
+
 - Component moves, module boundaries, props, types, or owner placement: read [`references/ownership.md`][ownership].
 - Dify UI wrappers or primitive state styling: read the package's [Public API authoring] and [Styling] contracts.
-- Jotai, form drafts, route identity, URL state, or persistence: read [`references/state.md`][state].
-- Generated contracts, nullable API data, Query, mutations, SSR, auth, or workspace state: read [`references/data.md`][data].
-- Hotkeys, focus, dialogs, menus, popovers, or other secondary surfaces: read [`references/interactions.md`][interactions] and the overlay guide it references when applicable. Also read [`references/state.md`][state] when the surface owns a draft or other local session state.
+- Jotai, graph-entry decisions, form drafts, shared client state, route identity, URL state, isolation/reset, or persistence: read [`references/state.md`][state].
+- Generated contracts, nullable API data, Query, mutations, SSR, authentication, or workspace state: read [`references/data.md`][data].
+- A feature graph that combines Jotai isolation with TanStack Query atoms or commands: read both [`references/state.md`][state] and [`references/data.md`][data].
+- Hotkeys, focus, dialogs, menus, popovers, or other secondary surfaces: read [`references/interactions.md`][interactions] and the overlay guide it references when applicable. Also read [`references/state.md`][state] when the surface owns a draft or session state.
 - Effects, navigation, memoization, preloading, or render cost: read [`references/runtime.md`][runtime].
 
+## Common Workflow
+
+Follow this order so component splitting does not precede ownership decisions:
+
+1. **Boundary and evidence:** identify the route, tab, workflow, or action surface that owns the behavior and lifetime. Inspect nearby implementation, tests, sibling state files, and established feature boundaries.
+2. **Current model:** identify generated data contracts and authoritative external inputs, then inventory state, queries, mutations, derived facts, commands, refs, and meaningful props edges.
+3. **Target graph and owners:** decide explicitly which values remain local and which enter the feature graph. Define authoritative bridges, graph nodes, component owners, and scope/reset boundaries before creating files or wiring components.
+4. **Re-cut the tree:** treat current files as evidence rather than target constraints. Keep, split, merge, remove, rename, promote, or demote components based on ownership, lifecycle, behavior, and independently changing visual regions.
+5. **Contracts and interactions:** place data, loading, empty, error, and handlers at the lowest real consumer. Cross true owner boundaries only with stable identity, a small immutable snapshot, placement, or a named command. Give forms and secondary surfaces explicit lifecycle owners.
+6. **Finish and verify:** remove copied state and unnecessary Effects, wrappers, memoization, or nullable coercion. Rerun the final owner, graph, props-edge, and reset audit, then verify observable behavior at the narrowest sufficient boundary.
+
 ## Scope And Verification
 
-Identify the behavior owner, state lifetime, and public contract from the nearby implementation and relevant references. Keep the change within that vertical slice unless the contract requires changes elsewhere. Verify the changed behavior and complete the owning package's required checks. For Web, read `web/docs/test.md` for test work and `web/docs/lint.md` for static checks. Dify UI verification is owned by `packages/dify-ui/docs/testing.md`.
+In architecture-audit and refactoring-design modes, do not modify code. In implementation mode, complete equivalent ownership fixes inside the audited feature when the target contract depends on them, but do not expand into unrelated features. Incremental slices may retain documented temporary edges; the final requested slice must pass the completion gate in [`references/audit.md`][audit].
+
+Run the checks documented by the owning package: `web/docs/test.md` or `web/docs/lint.md` for Web, and `packages/dify-ui/docs/testing.md` for Dify UI.
+
+[audit]: references/audit.md
 
 ## Tailwind CSS
 

.agents/skills/how-to-write-component/references/audit.md

@@ -0,0 +1,64 @@
+# Component Architecture Audit
+
+Read this document for architecture audits, refactoring designs, and the final ownership verification after an implementation refactor.
+
+## Audit Procedure
+
+For a named component, use it as the audit root. For a refactoring request, use the nearest route, page, feature entrypoint, or behavior owner whose state contract is changing.
+
+1. Build the complete locally owned rendered component tree from the root to every leaf. Follow imported feature components, conditional branches, lists, portals, dialogs, drawers, popovers, and secondary surfaces. Stop at third-party primitives, Dify UI primitives, or an explicit stable feature boundary, but record the props passed across the final edge.
+2. At every component, inventory React state and reducers, form and uncontrolled DOM state, URL and route state, Context/Jotai/store reads and writes, queries, mutations, refs that hold workflow or lifecycle state, custom-hook results, render-time derived facts, and workflow commands or handlers.
+3. For every value, record its authoritative owner/source, graph role, declaring component, consuming branches, lifetime and reset/isolation requirements, and whether it is local, shared, forwarded, mirrored, or persisted.
+4. Inspect every meaningful props edge. Mark each prop as consumed, forwarded unchanged, renamed, recomputed, mirrored into local state, or paired with lifecycle fields such as `data/pending/error/retry` and `open/onOpenChange`.
+5. Draw the current state graph in dependency order and assess ownership only after the complete paths are mapped. Group related problems at the highest incorrect owner instead of repeating the same issue for every descendant.
+6. Give every current local component an explicit target disposition: keep, split, merge, remove, rename, promote to an owner, or demote to presentation. Map every current state or workflow owner to a target component and reset boundary.
+7. Redraw the target rendered tree independently of the current file layout. Split only when state lifetime, interaction lifecycle, behavior ownership, or an independently changing visual region establishes a real boundary. Merge or remove components that only forward, rename, or obscure a single owner's contract.
+8. For refactoring design or implementation planning, define ordered migration slices with explicit state-file changes, component moves/splits/merges, observable verification boundaries, and intentionally temporary props edges.
+
+A rename, facade wrapper, props bag, Context, or provider around the same switchboard does not count as a boundary redesign. Correctness bugs may illustrate an ownership defect, but architecture-audit mode does not prioritize or severity-rank bug findings.
+
+## Audit Output
+
+Cover the following information. Merge sections or omit empty tables when the review is small, but do not omit applicable values, paths, edges, owners, or reset boundaries:
+
+1. **Review boundary:** root component, locally owned rendered paths, and stopping boundaries.
+2. **Rendered component tree:** every local branch and secondary surface followed.
+3. **State inventory:** owner/source, graph role, graph-entry decision, declaration, consumers, and lifetime/reset needs for every stateful value, query, mutation, ref, custom-hook result, derived fact, and command.
+4. **Props-edge ledger:** every meaningful parent-child edge and how each prop is treated.
+5. **Current architecture:** state graph, component owners, and ownership assessment.
+6. **Component dispositions:** the target disposition of every current local component and the destination of every current state/workflow owner.
+7. **Target architecture:** target rendered tree, state graph, owners, component contracts, and reset boundaries.
+8. **Migration slices:** required for refactoring design; include them in an audit when they materially clarify how to reach the target.
+
+Use compact tables when they make full accounting easier to verify:
+
+| Value | Source/role | Declared at | Consumers | Props path | Lifetime/reset | Recommended owner |
+| --- | --- | --- | --- | --- | --- | --- |
+
+| Edge | Prop | Treatment | Real consumer | Assessment |
+| --- | --- | --- | --- | --- |
+
+| Current component | Current responsibilities | Target disposition | Target owner(s) | Reason |
+| --- | --- | --- | --- | --- |
+
+| Target component | Owned state/workflow | Children | Public contract | Reset boundary |
+| --- | --- | --- | --- | --- |
+
+## Implementation Completion Gate
+
+Repeat the audit against the final code. Do not describe an implementation or refactor as complete until all applicable checks pass:
+
+- every locally owned rendered path, meaningful props edge, and stateful value is represented in the component tree, inventory, or ledger;
+- every current local component has a target disposition, and every current state/workflow owner maps to an implemented component and reset boundary;
+- every multi-consumer graph value has one authoritative bridge or graph node and a named owner;
+- route or URL identity is read directly by a single consumer or bridged once, not also threaded through descendant props;
+- query keys, observer objects, `refetch`, loading/error groups, and cache invalidation mechanics do not cross a boundary unless the child owns the query surface;
+- no page, hook, provider, or Context mainly destructures, renames, and redistributes another state machine;
+- components consume focused fields, named facts, or domain commands instead of rebuilding shared business conclusions;
+- query and mutation atoms remain cache-shared, while only resettable workflow primitives or boundary snapshots are scoped;
+- a feature scope that depends on application state still observes parent/global atom updates; a fresh `Provider` is used only when full-store isolation is an explicit requirement;
+- scoped-state verification covers parent-store interoperation, sibling-instance isolation when multiple instances are supported, and semantic-identity reset;
+- every remaining multi-layer prop edge is justified as stable identity, an immutable display snapshot, placement, or a named cross-boundary command;
+- the final rendered tree, state graph, owner map, contracts, and reset boundaries match the implemented code rather than only the initial design.
+
+If the user requests incremental commits, a slice may intentionally leave documented edges for a later slice. The final requested slice must still pass this gate.