docs: rebalance prose cleanup and add trimming skill

packages/fs/fs-policy/README.md

@@ -37,7 +37,7 @@ Three `fs/*` events (declared by `@deepseek-ai/dsh-fs`, dispatched by `@deepseek
 
 ## Observed state is the prior-observation record; freshness is provider CAS
 
-Observed state is a weak owner-to-target version map updated after every successful read or mutation. The plugin performs no filesystem I/O: it checks whether a version was observed and supplies that version to the provider's atomic mutation guard. State is discarded on plugin disposal and is not persisted across sessions.
+Observed state is a weak owner-to-target version map updated after every successful read or mutation; presence alone is the prior-observation record. The plugin performs no filesystem I/O: it supplies the observed version to the provider's atomic mutation guard. A windowed read observes the whole file version, so a later targeted edit is allowed only while that file remains unchanged. State is discarded on plugin disposal and is not persisted across sessions.
 
 ## Single-slot, first-wins
 

packages/fs/fs-policy/src/index.ts

@@ -1,7 +1,8 @@
 /**
- * The fs-policy plugin: observed-state, read-before-edit, and "write/edit must be based on the
- * version you read" — added on top of the `ctx.fs` provider seam through the `fs/*` event
- * gate, not through a method service.
+ * Event-only filesystem observation policy; it registers no service. A weak owner/target map
+ * records every successful read or mutation, single-slot intent listeners supply that version,
+ * and the provider performs the atomic freshness check. Without this plugin, tools retain the
+ * bare provider's unconditional mutation behavior. See the package README for composition rules.
  * @module @deepseek-ai/dsh-fs-policy
  */
 
@@ -110,7 +111,8 @@ export function apply(ctx: Context): void {
   // fs/edit-intent: occupy the single decision slot — do not call next().
   ctx.on('fs/edit-intent', (target, actor) => Promise.resolve().then(() => gate.editIntent(target, actor)))
 
-  // fs/observed: synchronous, side-effect-only WeakMap write.
+  // fs/observed must remain synchronous and non-throwing: the mutation already succeeded, and
+  // emit does not await promises. WeakMap.set satisfies that contract.
   ctx.on('fs/observed', (target, version, actor) => {
     gate.observe(target, version, actor)
   })

packages/fs/fs-policy/tests/policy.spec.ts

@@ -1,6 +1,4 @@
-/**
- * Tests for the fs-policy plugin: it registers no service, only the three `fs/*` listeners.
- */
+/** Event-level policy tests; no filesystem provider is needed because the plugin performs no I/O. */
 
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'