Extended FOC skills: 'Synapse SDK' and 'FOC Services'

skills/foc-platform/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: foc-platform
+description: Use when reasoning about Filecoin Onchain Cloud architecture, PDP, Warm Storage Service, Filecoin Pay, Filecoin Beam, Filecoin Pin/IPFS indexing, storage economics, or durable-state anchoring patterns.
+---
+
+# foc-platform
+
+Use this for product, protocol, and architecture decisions around Filecoin
+Onchain Cloud. For SDK-level code and API usage, also use
+`../synapse-sdk/SKILL.md`.
+
+## Hard Rules
+
+- Separate bytes, proofs, payments, and client orchestration.
+- Treat Filecoin as a durable service plane, not a live message bus.
+- PDP proves possession, not authorship, freshness, or semantic correctness.
+- Keep author, uploader, payer, publisher, and helper roles explicit.
+- Publish external pointers only after the upload result is final.
+- Dataset reuse is economic state; accidental dataset creation costs money.
+- Beam/CDN changes retrieval UX and egress economics, not storage correctness.
+- IPFS indexing changes discoverability, not ownership.
+
+## Fast Path
+
+1. Product model, costs, and service boundaries:
+   `references/core/architecture.md`
+2. Official sources and freshness rules:
+   `references/core/source-ledger.md`
+3. Durable-state anchoring patterns:
+   `references/use-cases/durable-state.md`
+4. Public content, IPFS indexing, and CDN interplay:
+   `references/use-cases/public-content.md`
+5. Authority, economics, and topology bugs:
+   `references/debugging/failure-modes.md`
+6. Role-splitting edge cases:
+   `references/edge-cases/authority.md`
+
+## References
+
+- `references/core/architecture.md`
+- `references/core/source-ledger.md`
+- `references/use-cases/durable-state.md`
+- `references/use-cases/public-content.md`
+- `references/debugging/failure-modes.md`
+- `references/edge-cases/authority.md`

skills/foc-platform/references/core/architecture.md

@@ -0,0 +1,45 @@
+---
+description: Current Filecoin Onchain Cloud architecture and economics.
+---
+
+# Architecture
+
+Verified `2026-03-23`.
+
+## Layers
+
+- `Synapse SDK`: client orchestration, provider selection, payments prep,
+  upload/retrieval APIs
+- `FWSS`: warm-storage service contract and dataset lifecycle
+- `PDPVerifier`: proof system that verifies providers still hold bytes
+- `Filecoin Pay`: continuous settlement rails in USDFC
+- `FilBeam`: CDN / performance retrieval path
+- `Filecoin Pin + IPNI`: public content discovery path for IPFS-style content
+
+## Data Model
+
+- bytes -> `pieceCid`
+- one provider + one dataset -> one payment relationship
+- multi-copy storage -> one committed copy per provider
+- dataset metadata drives reuse
+- piece metadata labels a single object
+
+## Economics
+
+- base storage: `2.50 USDFC / TiB / 30-day month`
+- minimum dataset rate: `0.06 USDFC / month`
+- new dataset sybil fee: `0.1 USDFC`
+- CDN setup on new CDN dataset: `1.0 USDFC`
+- CDN egress: `14 USDFC / TiB downloaded`
+- storage service expects roughly `30` days of prepayment runway
+
+## Product Choices
+
+- PDP only:
+  durable storage + retrievability
+- PDP + Beam:
+  low-latency retrieval
+- PDP + IPFS indexing:
+  public gateway/IPNI discoverability
+- PDP + signed payload:
+  durable provenance / state anchoring

skills/foc-platform/references/core/source-ledger.md

@@ -0,0 +1,36 @@
+---
+description: Official source order and freshness notes for Filecoin Onchain Cloud.
+---
+
+# Source Ledger
+
+Verified `2026-03-23`.
+
+## Primary Sources
+
+- docs:
+  - `https://docs.filecoin.cloud/`
+  - `https://docs.filecoin.cloud/core-concepts/architecture/`
+  - `https://docs.filecoin.cloud/core-concepts/pdp-overview/`
+  - `https://docs.filecoin.cloud/core-concepts/fwss-overview/`
+  - `https://docs.filecoin.cloud/core-concepts/filecoin-pay-overview/`
+  - `https://docs.filecoin.cloud/developer-guides/storage/storage-costs/`
+- SDK / contracts / examples:
+  - `https://github.com/FilOzone/synapse-sdk`
+  - `https://github.com/FIL-Builders/fs-upload-dapp`
+
+## Conflict Rules
+
+- Economics and service concepts: docs win.
+- Current API and export names: SDK source wins.
+- Example-app behavior is evidence, not protocol truth.
+- Prefer exact dates when discussing versions or publish times.
+
+## Fresh Facts
+
+- docs host is `docs.filecoin.cloud`
+- current npm latest:
+  - `@filoz/synapse-sdk` = `0.40.0`
+  - `@filoz/synapse-core` = `0.3.1`
+- current public architecture still centers on FWSS + PDP + Filecoin Pay +
+  Synapse SDK, with Beam/CDN and IPFS indexing as optional retrieval paths

skills/foc-platform/references/debugging/failure-modes.md

@@ -0,0 +1,58 @@
+---
+description: High-signal product and architecture failure modes on Filecoin Onchain Cloud.
+---
+
+# Failure Modes
+
+## Authority Bugs
+
+Symptoms:
+
+- one process builds bytes, another publishes the pointer
+- helper service can mutate anchor fields after upload
+- client-authored state becomes server-authored storage
+
+Fix:
+
+- collapse build/sign/upload/publish onto the actual state authority
+
+## Economic Bugs
+
+Symptoms:
+
+- storage costs spike unexpectedly
+- many tiny datasets appear
+- CDN costs look wrong
+
+Check:
+
+- volatile dataset metadata
+- accidental `source` changes
+- unnecessary new datasets
+- CDN setup fee vs recurring egress
+- copy count inflation
+
+## Partial-Success Bugs
+
+Symptoms:
+
+- app treats returned upload result as full success
+- one failed provider marks the whole job failed
+
+Check:
+
+- `complete`
+- committed `copies[]`
+- whether retries replaced failed providers
+
+## Topology Bugs
+
+Symptoms:
+
+- system stops working when helper services go down
+- durable storage path is also the live coordination path
+
+Fix:
+
+- keep helper services optional
+- keep durable anchoring separate from live transport

skills/foc-platform/references/edge-cases/authority.md

@@ -0,0 +1,43 @@
+---
+description: Role-splitting edge cases for Filecoin Onchain Cloud integrations.
+---
+
+# Authority
+
+## Keep These Roles Separate
+
+- author:
+  who created the bytes
+- uploader:
+  who executed the storage operation
+- payer:
+  who funds the rails
+- publisher:
+  who exposes the external pointer
+- helper:
+  who assists with credentials, funding, or transport
+
+## Safe Patterns
+
+- one actor owns all roles
+- delegated uploader acts for the payer, but the payload still proves author
+- helper service never invents or rewrites anchor outputs
+
+## Unsafe Patterns
+
+- payer identity used as a proxy for authorship
+- unsigned payloads later treated as provenance-bearing records
+- stale `pieceCid` / timestamp / dataset fields carried forward to new records
+- helper outage breaking the core protocol path
+
+## Review Test
+
+Ask, in order:
+
+1. Who produced the exact uploaded bytes?
+2. Who signed them?
+3. Who paid?
+4. Who published the pointer?
+5. Can any other process rewrite those answers later?
+
+If the answers drift across systems, the authority boundary is probably wrong.

skills/foc-platform/references/use-cases/durable-state.md

@@ -0,0 +1,38 @@
+---
+description: Durable-state and signed-record anchoring patterns on Filecoin Onchain Cloud.
+---
+
+# Durable State
+
+Use this when the uploaded bytes are more than files: signed reports, audit
+records, manifests, local app state, or other data whose authorship matters.
+
+## Correct Order
+
+1. Produce canonical bytes at the authority that owns the state.
+2. Compute the local hash / root over those bytes.
+3. Sign the bytes or a deterministic envelope containing the root.
+4. Upload to Filecoin.
+5. Persist the real anchor outputs:
+   `pieceCid`, `providerId`, `dataSetId`, `pieceId`, anchor timestamp.
+6. Publish external pointers or manifests.
+
+## Never Do
+
+- publish the pointer first, fill storage fields later
+- let a helper service invent the state hash after the fact
+- infer authorship from the payer wallet
+- treat PDP as a signature system
+
+## Role Split
+
+Valid:
+
+- author = uploader = signer
+- author != payer, but the uploaded payload contains the author's signature
+- helper only issues credentials, funding, or transport assistance
+
+Invalid:
+
+- helper uploads unsigned state and claims the state is user-authored
+- one process computes the pointer, another later patches in storage IDs

skills/foc-platform/references/use-cases/public-content.md

@@ -0,0 +1,34 @@
+---
+description: Public-content patterns combining IPFS indexing and Beam/CDN.
+---
+
+# Public Content
+
+## Use IPFS Indexing When
+
+- content should resolve by IPFS root CID
+- public gateways or IPNI discovery matter
+- the uploaded bytes are CAR / IPLD-friendly content
+
+Pattern:
+
+- dataset metadata includes `withIPFSIndexing`
+- piece metadata includes `ipfsRootCID`
+- verify gateway/IPNI visibility before claiming public availability
+
+## Use Beam / CDN When
+
+- low-latency retrieval matters
+- traffic volume justifies egress costs
+- public discovery is not enough on its own
+
+## Do Not Conflate
+
+- IPFS indexing:
+  discoverability / addressing
+- Beam / CDN:
+  retrieval performance / egress path
+- PDP:
+  storage possession proof
+- payload signature:
+  authorship / provenance

skills/synapse-sdk/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: synapse-sdk
+description: Use when integrating, upgrading, debugging, or operating @filoz/synapse-sdk / @filoz/synapse-core for Filecoin Onchain Cloud storage, session keys, multi-copy uploads, dataset reuse, provider routing, or PDP-backed retrieval.
+---
+
+# synapse-sdk
+
+Use this for current 2026 Synapse work. Treat pre-viem, pre-0.37, or
+pre-`source` examples as migration material, not default guidance.
+
+## Hard Rules
+
+- Prefer current truth in this order:
+  `references/core/source-ledger.md`
+- Default to `Synapse.create({...})`.
+- Use `new Synapse({ client, sessionClient? })` only when a wallet client
+  already exists.
+- Pass a deliberate `source`; stable non-empty string is default, `null` only
+  when shared namespace reuse is intentional.
+- Call `prepare()` before first upload, large upload, or storage-setting change.
+- `upload()` is partial-success: returned result means at least one committed
+  copy; `complete === true` means all requested copies succeeded.
+- Dataset metadata is low-cardinality routing state. Piece metadata is
+  object-specific state.
+- Session keys must have synced expirations before client construction.
+- PDP proves possession, not authorship; sign uploaded bytes when authenticity
+  matters.
+
+## Fast Path
+
+1. Current versions, limits, chains, cost knobs:
+   `references/core/facts.md`
+2. Default upload/download and split flows:
+   `references/use-cases/flows.md`
+3. Delegated signing:
+   `references/use-cases/session-keys.md`
+4. Funding, partial copies, metadata surprises:
+   `references/debugging/failures.md`
+5. Namespace, dataset explosion, provenance pitfalls:
+   `references/edge-cases/namespaces.md`
+
+## References
+
+- `references/core/facts.md`
+- `references/core/source-ledger.md`
+- `references/use-cases/flows.md`
+- `references/use-cases/session-keys.md`
+- `references/debugging/failures.md`
+- `references/edge-cases/namespaces.md`