diff --git a/.custodian-brief.md b/.custodian-brief.md deleted file mode 100644 index 459de8e..0000000 --- a/.custodian-brief.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Custodian Brief - fluid-telegram - -**Project:** fluid-telegram -**Domain:** infotech -**State Hub:** http://127.0.0.1:8000 -**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a` - -## Open Workplans - -### Bootstrap State Hub integration - -Workplan file: `workplans/FLUID-WP-0001-statehub-bootstrap.md` - -Open tasks: -- T01 - Review generated integration files -- T02 - Verify local developer workflow -- T03 - Seed first real workplan - -## Session Start - -1. Read `INTENT.md`, `SCOPE.md`, and `AGENTS.md`. -2. Check inbox: `GET /messages/?to_agent=fluid-telegram&unread_only=true`. -3. Scan `workplans/`. -4. Update task statuses in workplan files as work progresses. - -Last generated: 2026-09-04 diff --git a/.gitignore b/.gitignore deleted file mode 100644 index e4e0199..0000000 --- a/.gitignore +++ /dev/null @@ -1,5 +0,0 @@ -# state-hub: track .claude/rules -# Claude Code local state (track shared rules; ignore machine-specific files) -.claude/* -!.claude/rules/ -!.claude/rules/*.md diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 342d057..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,205 +0,0 @@ -# fluid-telegram — Agent Instructions - -## Repo Identity - -**Purpose:** Fluid interface for telegram messaging and interaction platform. - -**Domain:** infotech -**Repo slug:** fluid-telegram -**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a` -**Workplan prefix:** `FLUID-WP-` - ---- - -## State Hub Integration - -The Custodian State Hub tracks work across all domains. Codex uses HTTP REST and -the `statehub` CLI by default. MCP is opt-in because the current Codex MCP bridge -adds severe call latency; the full administrative MCP surface remains available -to clients that need it. - -| Context | URL | -|---------|-----| -| Local workstation | `http://127.0.0.1:8000` | -| Remote via tunnel | `http://127.0.0.1:18000` | -| Optional local edge relay | http://127.0.0.1:18080 | - -When an operator has enabled the edge relay, set API_BASE to the relay URL. -Queueable writes return an explicit queued receipt if the central hub is -unreachable. Treat that as pending local evidence, then ask the operator to run -statehub outbox status/replay after connectivity returns. - -Codex workspace-write sandboxes need network access enabled to reach the host's -loopback listener. Bootstrap this once with `make -C ~/state-hub configure-codex` -and restart Codex. The canonical REST health endpoint is `/state/health`, not -`/health`. If a sandboxed loopback probe fails, retry it with escalated execution -before declaring State Hub unavailable; a managed Codex permission profile may -still enforce isolated networking. Experimental MCP can be enabled explicitly -with `make -C ~/state-hub configure-codex WITH_MCP=1`. - -### Orient at session start - -```bash -# Offline brief — works without hub connection -cat .custodian-brief.md - -# Active workplans for this domain -curl -s "http://127.0.0.1:8000/workplans/?topic_id=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" \ - | python3 -m json.tool - -# Check inbox -curl -s "http://127.0.0.1:8000/messages/?to_agent=fluid-telegram&unread_only=true" \ - | python3 -m json.tool -``` - -Mark a message read: -```bash -curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ - -H "Content-Type: application/json" -d '{}' -``` - -### Log progress (required at session close) - -```bash -curl -s -X POST http://127.0.0.1:8000/progress/ \ - -H "Content-Type: application/json" \ - -d '{ - "summary": "what was done", - "event_type": "note", - "author": "codex", - "workplan_id": "", - "task_id": "" - }' -``` - -Omit `workplan_id` / `task_id` when not applicable. - -### Update task status - -```bash -curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ - -H "Content-Type: application/json" \ - -d '{"status": "progress"}' -# values: wait | todo | progress | done | cancel -``` - -### Flag a task for human review - -```bash -curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ - -H "Content-Type: application/json" \ - -d '{"needs_human": true, "intervention_note": "reason"}' -``` - ---- - -## Session Protocol - -**Start:** -1. `cat .custodian-brief.md` — domain goal and open workplans (offline-safe) -2. Check inbox: `GET /messages/?to_agent=fluid-telegram&unread_only=true`; mark read -3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks -4. Check human-needed tasks: `GET /tasks/?needs_human=true` - -**During work:** -- Update task statuses in workplan files as tasks progress -- Record significant decisions via `POST /decisions/` - -**Close:** -1. Update workplan file task statuses to reflect progress -2. If finishing a workplan: hand off **residuals** as live work records first - (intake with `origin: residual` + `origin_ref: `, or a next workplan / - decision / engagement). Do not park leftovers only in prose or `SCOPE.md`. - Canon: `the-custodian/canon/standards/work-record-types_v0.1.md` § Residuals. -3. Log: `POST /progress/` with a summary of what changed (name handoff ids) -4. After workplan file changes, run: - ```bash - uv run --project ~/repo-manager rmgr sync --path . --push - ``` - This assigns only missing deterministic identifiers, verifies the pushed - Forgejo commit and `primary/railliance01`, then requests one central - reconciliation. A queued receipt is pending evidence; rerun after - connectivity returns. Use `statehub fix-consistency` for a separate deep audit. - ---- - -{CREDENTIAL_ROUTING} - - - - ---- - -## Workplan Convention (ADR-001) - -Work items originate as files in this repo — not in the hub. The hub is a -read/cache/index layer that rebuilds from files. - -**File location:** `workplans/FLUID-WP-NNNN-.md` - -**Archived location:** finished workplans may move to -`workplans/archived/YYMMDD-FLUID-WP-NNNN-.md`. The `YYMMDD` prefix is -the completion/archive date; the frontmatter `id` does not change. - -**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use -`workplans/ADHOC-YYYY-MM-DD.md`, workplan id -`FLUID-WP-ADHOC-YYYY-MM-DD`, and task ids -`FLUID-WP-ADHOC-YYYY-MM-DD-T01`, etc. `FLUID-WP` includes its final `-WP` -token. Unqualified historic `ADHOC-*` ids are grandfathered and must not be -copied into new records. Use this only for low-risk work completed directly; -create a normal workplan for anything needing analysis, design, approval, -dependencies, or multiple phases. - -**Frontmatter:** - -```yaml ---- -id: FLUID-WP-NNNN -type: workplan -title: "..." -domain: infotech -repo: fluid-telegram -status: proposed | ready | active | blocked | backlog | finished | archived -owner: codex -topic_slug: ... -created: "YYYY-MM-DD" -updated: "YYYY-MM-DD" -state_hub_workstream_id: "" # deterministic UUIDv5; managed by Repo Manager ---- -``` - -Use `proposed` for a new draft, `ready` after review against current repo -state, and `finished` after implementation. `stalled` and `needs_review` are -derived health labels, not frontmatter statuses. - -**Terminology:** workplan is the fleet term; `workstream` appears only in legacy -API/MCP/frontmatter bridges until `STATE-WP-0069` retires them — see -`the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`. - -**Task block format** (one per `##` section): - -``` -## Task Title - -` ` `task -id: FLUID-WP-NNNN-T01 -status: wait | todo | progress | done | cancel -priority: high | medium | low -state_hub_task_id: "" # deterministic UUIDv5; managed by Repo Manager -` ` ` - -Task description text. -``` - -Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work. - -**Residuals when finishing:** actionable leftovers become live work records -before `status: finished` — usually an intake (`origin: residual`, -`origin_ref: FLUID-WP-NNNN`) or a spawned workplan. Residual is a *role*, -not a kind. Fleet list lives on State Hub, not in `SCOPE.md`. - -To create a new workplan: -1. Write the file following the format above -2. Run `uv run --project ~/repo-manager rmgr sync --path . --push`. -3. Run `statehub fix-consistency` only when a separate deep audit is needed. diff --git a/INTENT.md b/INTENT.md deleted file mode 100644 index 80e4fa5..0000000 --- a/INTENT.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -repo: fluid-telegram -updated: "2026-09-04" ---- - -# INTENT - -## Why it exists - -Fluid interface for telegram messaging and interaction platform. - -Fluid interface for telegram messaging and interaction platform. - -## Governing principle - -This repository should stay focused on the purpose above. Work that changes its -authority, ownership boundaries, or operational promises should be captured in a -workplan before implementation. - -## What it enables - -- A coding agent can understand why the repository exists before changing it. -- State Hub can register and coordinate work for this repository. -- Future workplans can stay connected to the repository's intended role. diff --git a/InterfaceEvolutionIntent.md b/InterfaceEvolutionIntent.md deleted file mode 100644 index 8f1dd0d..0000000 --- a/InterfaceEvolutionIntent.md +++ /dev/null @@ -1,507 +0,0 @@ -# Interface Evolution Intent — helix-forge-telegram-publishing - -**Document version:** IEI-1 -**Status:** active -**Last reviewed:** 2026-09-04 - ---- - -## 1. Purpose - -This document defines the evolutionary intent and governance boundary of the -FLUID interface that publishes HelixForge material to Telegram. - -It is subordinate to `helix-forge/INTENT.md` and does not redefine HelixForge's -mission. It answers one question: - -> How may this interface evolve while remaining faithful to the service it -> represents? - -The FLUID Daimon must treat this document as a constitutional constraint. - ---- - -## 2. Parent Intent - -**Parent service/repository:** `helix-forge` - -**Parent intent document:** `helix-forge/INTENT.md` - -**Relevant parent mission:** HelixForge exists to turn intent into structure, -structure into capability, and capability into lasting progress. The Hall of -Helix is where that work's participants are acknowledged. This interface carries -those acknowledgements outward. - ---- - -## 3. Interface Identity - -**Interface name:** HelixForge Telegram Publishing - -**Interface identifier:** `helix-forge-telegram-publishing` - -**Current operational authority mode:** FLUID-2 - -FLUID-2 (Advisory) is a deliberate choice, not a starting point to be outgrown -on a schedule. The Daimon may observe, classify pressure and propose -adaptations. It may not generate implementations, run experiments unattended, or -promote anything. This interface publishes under HelixForge's name to an -audience that did not consent to being experimented on carelessly, and the cost -of a bad post is reputational rather than recoverable. - -Raising the mode is a governance change under §20, not an operational decision. - -**Protocols / interface styles:** REST over HTTP (JSON) - ---- - -## 4. Mission - -### Mission statement - -> Make hall-of-helix entries reliably and faithfully available to a Telegram -> audience, without the people writing them having to think about Telegram. - -An entry is written once, as Markdown, in `hall-of-helix/entries/`. Everything -about how it becomes a Telegram post — length, formatting, media, threading — -is this interface's problem and nobody else's. - -### Success looks like - -- A finished hall entry reaches the channel without a human reformatting it. -- The published form is faithful: no entry is silently truncated, and no - attribution is lost. -- Publishing twice does not post twice. -- When Telegram's constraints and the entry's shape conflict, the conflict - surfaces as recorded pressure rather than as a mangled post. - ---- - -## 5. Intended Consumers - -### Primary consumer cohorts - -| Cohort | Description | Importance | Notes | -|---|---|---|---| -| `hall-publishing-jobs` | Automation in `hall-of-helix` that publishes finished entries | High | The reason this interface exists | -| `helix-forge-agents` | Agent sessions announcing their own completed work | High | Highest-volume caller; supplies the richest pressure signal | -| `operators` | Humans publishing or correcting by hand | Medium | Low volume, high consequence | - -### Secondary cohorts - -| Cohort | Description | Importance | Notes | -|---|---|---|---| -| `telegram-subscribers` | Readers of the channel | Medium | Not API consumers; observed through engagement, never individually | - -### Explicitly unsupported cohorts - -- Third-party services outside the HelixForge boundary. -- Anonymous or unauthenticated callers. -- Anything seeking to publish content it did not author. - ---- - -## 6. Capability Domain - -### In scope - -- Publishing hall-of-helix entries to a Telegram channel (Canon PUB-01). -- Rendering an entry into Telegram's message forms (Canon PUB-02, MED-02). -- Publication state: what was published, when, as which message. -- Idempotency and correction of previously published entries. -- Bot identity presentation (Canon BOT-01). - -### Conditionally in scope - -Capabilities that may be introduced if evidence justifies them: - -- Scheduling a publication for a later time. -- Publishing other HelixForge artifacts, such as release notes. -- Attaching entry visuals as media (Canon MED-01). -- A linked discussion group for comments. - -### Out of scope - -- Inbound bot commands and conversation (Canon BOT-02, AGT-01). A second - revision family may add this later; it is not this interface today. -- Payments and paid content (Canon PAY-*). -- Mini Apps (Canon APP-*). -- Moderation and membership management (Canon COM-02, COM-03). -- Any capability requiring a Telegram user account rather than a bot. - ---- - -## 7. Responsibility Boundaries - -### Responsibilities owned by this interface - -- Representation: how an entry becomes one or more Telegram messages. -- Composition: assembling an entry, its metadata and its visual. -- Validation: refusing an entry that cannot be published faithfully. -- Routing: which revision serves a publication request. -- Idempotency: recognising an entry it has already published. - -### Responsibilities owned by backend systems - -| Backend | Responsibility | Boundary | -|---|---|---| -| Telegram Bot API | Message delivery, channel state, subscriber identity | FLUID may request delivery. It may not assume a limit will move, and must treat platform constraints as fixed. | -| `hall-of-helix` | Entry content, its correctness, and whether it is finished | FLUID may read entries. It must never edit one to make it publishable. | -| OpenBao | Custody of the bot token | FLUID receives a credential. It never stores, logs or forwards one. | - -### Explicit non-authority - -The Daimon must not autonomously: - -- create, rename or delete Telegram channels, groups or bots; -- change channel membership, administrators or permissions; -- read, rotate or re-scope the bot token; -- edit or truncate a hall-of-helix entry to fit a platform constraint; -- publish to any chat other than those declared in the routing configuration; -- post on behalf of a person who has not asked for it. - -The last of these matters most. A hall entry is a first-person account someone -wrote about their own work. Publishing it is an act taken on their behalf, and -that authority comes from their having written it — not from the interface -finding it convenient. - ---- - -## 8. Consumer Expectation Model - -### Concepts consumers should naturally understand - -- An **entry** is the unit of publication, identified by its hall entry id. -- Publishing is **idempotent** on that id. -- A **publication** has state: pending, published, failed, superseded. - -### Interaction patterns considered natural - -- Publish one finished entry, then check its state. -- Re-publish the same entry after a correction and get the same message updated. -- List what has been published to reconcile against the hall. - -### Expectations that should be discouraged - -- That Telegram formatting is Markdown. It is not, and entries that assume so - will render wrongly. -- That an entry appears instantly. Rate limits are real. -- That a long entry arrives as one message. It cannot, and the interface's job - is to make that invisible rather than to pretend otherwise. - ---- - -## 9. Optimization Preferences - -### Active optimization regime - -`ADOPTION` — the channel has no audience yet. Until it does, discoverability and -client utility matter more than efficiency, and cost is negligible at this -volume. - -### Fitness priorities - -| Dimension | Priority | Target / Constraint | Notes | -|---|---:|---|---| -| Correctness | High | No entry published in a form that loses content | Hard guardrail | -| Client utility | High | One call publishes one entry | The reason the interface exists | -| Reliability | High | Publication succeeds or reports why | | -| Discoverability | High | A reader can reach the full entry | Drives the first experiment | -| Security | High | Token never leaves its custody | Hard guardrail | -| Compatibility | Medium | Versioned evolution | Few consumers, all internal | -| Simplicity | Medium | Prefer one publication concept | | -| Performance | Low | Publication is not latency-sensitive | Minutes are acceptable | -| Operational cost | Low | Negligible at this volume | | - -### Automatic recommendation policy - -`advisory` — the Daimon may recommend regime changes. It may not enact one. - ---- - -## 10. Complexity Budget - -### Complexity dimensions - -| Dimension | Current | Preferred | Maximum | Scoring method | -|---|---:|---:|---:|---| -| Surface area (operations) | 3 | 4 | 8 | Count of declared operations | -| Concept count | 2 | 3 | 5 | entry, publication | -| Parameter dimensionality | 4 | 6 | 12 | Declared parameters across operations | -| Semantic overlap | 0 | 0 | 1 | Operations meaning the same thing | -| Alternative-path count | 1 | 1 | 3 | Ways to achieve one outcome | -| Backend composition count | 1 | 2 | 3 | Backends per operation | -| Active revision count | 1 | 2 | 3 | Concurrently routable revisions | - -### Complexity policy - -- New capability should replace or generalize existing capability where - reasonable. -- Semantic duplication is rejected unless justified in writing. -- Repeated special-case pressure triggers an abstraction review rather than - another endpoint. -- A candidate exceeding a hard maximum must not be promoted. -- Presentation adaptations do not consume surface-area budget: they change how - an entry is rendered, not what the interface offers. - ---- - -## 11. Compatibility Policy - -### Compatibility posture - -`VERSIONED` - -### Rules - -- Published revision semantics must not change silently. -- Breaking changes require a successor revision. -- Every consumer is internal and known, so a breaking change is a coordination - problem rather than a public one — but it is still a successor revision. -- A change to how an entry is *rendered* is a presentation adaptation and does - not break the contract, even though readers will notice it. - -### Coexistence expectations - -**Default maximum concurrent major revisions:** 2 - -**Default deprecation period:** 30 days after the last call from any consumer - -**Migration assistance required:** yes — this interface has few enough consumers -that migration means telling their owners directly. - ---- - -## 12. Revision and Experiment Policy - -### Allowed concurrent exposure - -| Revision class | Production traffic allowed? | Max share | Approval required? | -|---|---|---:|---| -| stable | yes | 100% | no | -| candidate | yes | 30% | yes, human | -| experiment | yes | 20% | yes, human | -| deprecated | yes | 100% | no | -| retired | no | 0% | n/a | - -### Evolution velocity controls - -The Daimon should slow or freeze promotion when: - -- any entry has been published in a form that lost content; -- the bot has been rate-limited by Telegram in the last 24 hours; -- a security event has touched the token; -- an experiment is already running. Concurrency limit: 1. - -The Daimon may accelerate experimentation when: - -- the channel has more than 100 subscribers, giving experiments real power; -- the last three experiments completed without a guardrail breach. - -**Note on experiment power.** At current volume — roughly one entry published -per week — an experiment needs months to reach a decidable sample. The evaluator -will report INCONCLUSIVE, and that is the correct answer. Do not shorten windows -to force a verdict. - ---- - -## 13. Hypothesis Policy - -### Minimum evidence for hypothesis creation - -- At least 5 independent observations, or one unavoidable structural constraint. -- Observation window of at least 14 days for behavioural pressure. -- A structural constraint (a platform limit) may found a hypothesis immediately; - it does not need repetition to be real. - -### Required hypothesis fields - -observation, explanation, proposed adaptation, expected outcome, measurement, -success criteria, guardrails, complexity impact, risk, expected learning value. - -### Competing hypotheses - -`encouraged` — the first pressure this interface faces has at least two -defensible answers, and choosing between them by argument rather than evidence -is exactly the habit FLUID exists to break. - -### Reach preference - -Prefer the smallest sufficient adaptation. This interface is small enough that a -high-reach abstraction would be speculative; revisit when there are more than -three distinct kinds of pressure. - ---- - -## 14. Adaptation Authority - -| Adaptation class | Observe | Propose | Generate | Experiment | Promote | -|---|---:|---:|---:|---:|---:| -| Presentation | yes | yes | no | no | no | -| Contract | yes | yes | no | no | no | -| Composition | yes | yes | no | no | no | -| Implementation | yes | yes | no | no | no | -| Requirement escalation | yes | yes | yes | n/a | n/a | - -Every `Generate`, `Experiment` and `Promote` column is `no`, which is what -FLUID-2 means. Requirement escalation is the exception: the Daimon may write a -structured backend requirement, because that artifact is a request to someone -else and carries no authority of its own. - -### Absolute prohibitions - -The Daimon must not autonomously: - -- expand authorization scope; -- weaken tenant isolation; -- bypass deterministic security controls; -- reinterpret legal constraints; -- create backend authority it does not possess; -- publish anything to a live channel; -- alter the content of a hall entry. - ---- - -## 15. Security Requirements - -### Authentication - -Consumers authenticate to the gateway. The bot token authenticates the adapter -to Telegram and is never a consumer credential. - -### Authorization - -Only declared cohorts may publish. `telegram-subscribers` is an observed -population, not a caller. - -### Tenant isolation - -Single tenant. The interface serves HelixForge and no one else. - -### Data handling - -Telegram user identity (Canon ID-01) must not enter the evidence store in any -form. Subscriber engagement is recorded only as aggregate counts, subject to the -cohort minimum size. This is a hard constraint: readers of a public channel have -not consented to individual observation, and a framework built to learn from -consumers must not quietly learn about audiences. - -### Logging and provenance - -Every publication records which entry, which revision, which message, and which -consumer asked. The bot token appears in no log, error, telemetry event or -evidence record. - -### AI boundary - -AI-generated changes must pass deterministic security policy, tests, -authorization validation and release controls. At FLUID-2 no AI-generated change -reaches this interface at all. - ---- - -## 16. Quality Requirements - -| Quality attribute | Requirement | Hard guardrail? | -|---|---|---:| -| Correctness | No published entry loses content or attribution | yes | -| Idempotency | Publishing an entry twice yields one publication | yes | -| Availability | Best effort; publication may be retried | no | -| Reliability | A failed publication reports why and may be retried safely | yes | -| p95 latency | Under 10s excluding Telegram rate limiting | no | -| Error rate | Under 1% of publication attempts | yes | -| Security | Token never leaves custody | yes | -| Auditability | Every publication traceable to entry, revision and caller | yes | -| Rollback | Any revision can be replaced by its predecessor within one policy generation | yes | - ---- - -## 17. Economic Constraints - -### Adaptive compute budget - -| Budget | Limit | -|---|---:| -| analysis per day | 1 classification pass | -| hypothesis generation | manual only at FLUID-2 | -| candidate generation | not permitted at FLUID-2 | -| concurrent experiments | 1 | -| autonomous implementation effort | none | - -### Cost policy - -- Adaptive budget exhaustion must not affect publication. -- The dominant cost here is human attention, not compute. A hypothesis that - needs more review time than the improvement is worth should be deferred. - ---- - -## 18. Backend Capability Escalation - -### Preferred requirement destination - -Telegram platform constraints cannot be escalated to anyone — there is no -recipient. A requirement naming a Telegram limitation is recorded as evidence -for **boundary learning** instead, and the interface adapts around the -constraint or declares the demand out of scope. - -Requirements against `hall-of-helix` (entry structure, metadata) go to that -repository as an issue referencing the originating hypothesis. - -### Required response states - -ACCEPTED, PLANNED, AVAILABLE, PARTIALLY_AVAILABLE, OUT_OF_SCOPE, REJECTED, -SUPERSEDED. - -### Boundary-learning policy - -Repeated OUT_OF_SCOPE or REJECTED responses trigger a review of whether the -demand belongs to a neighbouring interface — most likely `fluid-x` or -`fluid-substack`, which face the same publishing problem under different -platform constraints. - ---- - -## 19. Audit and Provenance Policy - -For every promoted change the system must retain enough evidence to reconstruct -originating pressure, hypothesis, candidate, verification, approval, deployment, -affected cohorts, measured outcome and final disposition. - -### Retention period - -Evidence: 365 days. Publication records: indefinite, because they are the record -of what was said in HelixForge's name. - -### Immutable evidence store - -The fluid-core evidence store, append-only at the database. - ---- - -## 20. Review and Amendment - -### Amendment authority - -Bernd Worsch, as the owner of `helix-forge`. An amendment is a governance change -and is recorded as a new intent version; the previous version stays retrievable -because revisions published under it were governed by it. - -### Review cadence - -On any of: raising the authority mode, adding a capability family currently out -of scope, the first 100 subscribers, or annually. - -### Last reviewed - -2026-09-04 (initial) - ---- - -## 21. Summary - -The Daimon should optimize aggressively inside this document and remain -conservative at its boundaries. - -This interface may evolve in how it presents an entry. It may not evolve in -whose voice it speaks. diff --git a/README.md b/README.md index 1716279..1d8271e 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,3 @@ # fluid-telegram -Fluid interface for telegram messaging and interaction platform. - -## Status - -The FLUID interface `helix-forge-telegram-publishing` is prepared but not yet -live. Governance, contract, seed hypotheses and the adapter's connector contract -are in place; the bot, the channel and the adapter itself are not. - -- Governance: [`InterfaceEvolutionIntent.md`](InterfaceEvolutionIntent.md) -- Work: [`workplans/FT-WP-0001-telegram-identity-and-hall-channel.md`](workplans/FT-WP-0001-telegram-identity-and-hall-channel.md) -- Handover from fluid-core: `fluid-core/docs/handover/fluid-telegram.md` +Fluid interface for telegram messaging and interaction platform. \ No newline at end of file diff --git a/SCOPE.md b/SCOPE.md deleted file mode 100644 index 6209022..0000000 --- a/SCOPE.md +++ /dev/null @@ -1,32 +0,0 @@ -# SCOPE - -> This file was generated by `statehub register`. Refine it as the repository -> boundaries become clearer. - -## One-liner - -Fluid interface for telegram messaging and interaction platform. - -## Core Idea - -fluid-telegram exists to provide the capability described in INTENT.md. - -## In Scope - -- Maintain the repository's primary implementation. -- Keep docs, tests, and operational metadata current. - -## Out of Scope - -- Own unrelated adjacent systems. -- Make irreversible operational decisions without human approval. - -## Current State - -- Status: active; implementation and stability should be verified by the repo agent. - -## Getting Oriented - -- Start with: INTENT.md -- Agent instructions: AGENTS.md -- Workplans: workplans/ diff --git a/TelegramCapabilityCanon.md b/TelegramCapabilityCanon.md deleted file mode 100755 index 758698d..0000000 --- a/TelegramCapabilityCanon.md +++ /dev/null @@ -1,1536 +0,0 @@ -# Telegram Capability Canon - -**Status:** Draft v0.1 -**Date:** 2026-09-03 -**Purpose:** Canonical capability model for using Telegram as a messaging, publishing, community, application, commerce, and human/agent interaction platform. - ---- - -## 1. Purpose - -This canon provides a durable capability model for Telegram. - -It is intentionally not organized around the Telegram user interface or a chronological list of product features. Instead, it describes Telegram as a set of reusable platform capabilities that can be mapped to concrete products, communities, businesses, automations, and agentic systems. - -The primary questions are: - -1. What capability does Telegram provide? -2. Which Telegram surface exposes it? -3. Can it be accessed or controlled programmatically? -4. Can a bot or autonomous agent participate? -5. What are the important operational, security, and commercial constraints? -6. When should Telegram be treated as the system of record, and when should it remain only an interaction surface? - -The canon is designed to support projects such as `telegram-edge`, community platforms such as the Coulomb Society, agentic personalities, publishing systems, customer communication, and Telegram-based applications. - ---- - -# 2. Platform Model - -Telegram should be treated as six overlapping platforms: - -```text -Telegram -│ -├── Messaging Platform -│ ├── person ↔ person -│ ├── person ↔ bot -│ ├── group interaction -│ └── voice / video -│ -├── Publishing Platform -│ ├── channels -│ ├── stories -│ ├── public posts -│ └── live media -│ -├── Community Platform -│ ├── groups -│ ├── topics -│ ├── channels -│ ├── communities -│ └── moderation -│ -├── Application Platform -│ ├── bots -│ ├── mini apps -│ ├── identity -│ ├── payments -│ └── external integrations -│ -├── Commerce / Business Platform -│ ├── business accounts -│ ├── customer communication -│ ├── payments -│ ├── subscriptions -│ ├── monetization -│ └── advertising -│ -└── Human / Agent Interaction Platform - ├── AI bots - ├── streaming responses - ├── guest bots - ├── managed bots - ├── bot-to-bot communication - └── delegated business automation -``` - -These platforms share identity, messaging, discovery, media, permission, notification, and payment primitives. - ---- - -# 3. Capability Levels - -Each capability in this canon can be considered at five implementation levels. - -| Level | Meaning | -|---|---| -| **L0 — Human UI** | Available to a normal Telegram user through an official client. | -| **L1 — Bot Accessible** | A Telegram bot can participate using the Bot API. | -| **L2 — Application Accessible** | Mini Apps or external services can integrate with the capability. | -| **L3 — Client/API Accessible** | Full Telegram API / MTProto / TDLib clients can access or implement the capability. | -| **L4 — Agentic** | The capability is suitable for delegated or autonomous software-agent participation. | - -A capability may exist at more than one level. - ---- - -# 4. Messaging Capabilities - -## MSG-01 — One-to-One Messaging - -Telegram provides persistent cloud-based one-to-one conversations. - -### Functions - -- text messages; -- replies; -- forwarding; -- message editing; -- message deletion; -- reactions; -- rich formatting; -- links; -- media; -- files; -- contacts; -- locations; -- voice messages; -- video messages; -- polls where supported; -- search; -- pinned content; -- scheduled messages; -- repeating scheduled messages. - -### Automation - -Bots provide a first-class machine participant in private chats. - -### Agentic relevance - -**High.** - -A private bot conversation is one of the cleanest Telegram surfaces for: - -- personal assistants; -- AI agents; -- workflow interaction; -- approvals; -- notification delivery; -- command interfaces; -- conversational applications. - -### Design note - -Telegram should normally be treated as the **interaction surface**, not the sole persistent state store for sophisticated applications. - ---- - -## MSG-02 — Group Messaging - -Telegram supports large multi-party conversations. - -### Functions - -- persistent shared history; -- replies; -- mentions; -- reactions; -- member permissions; -- administrator roles; -- pinned messages; -- media and files; -- polls and quizzes; -- bots; -- topics; -- moderation; -- member tags; -- voice/video sessions; -- join requests; -- invite links. - -### Scale - -Telegram groups can support very large communities, including supergroups with up to hundreds of thousands of members. - -### Agentic relevance - -**Very high.** - -Groups can host: - -- moderator agents; -- research agents; -- question-answering agents; -- community managers; -- workflow bots; -- onboarding assistants; -- summarization agents; -- security and policy enforcement systems. - ---- - -## MSG-03 — Topics / Forum Conversations - -Groups may be divided into topic-oriented threaded spaces. - -### Uses - -- project discussions; -- support cases; -- subject-specific conversations; -- working groups; -- structured community areas; -- agent-specific work contexts. - -### Agentic relevance - -**High.** - -Topics provide a practical scope boundary for context and agent behavior. - ---- - -## MSG-04 — Ephemeral Bot Interaction - -Telegram supports bot responses inside groups that are visible only to the invoking user. - -### Uses - -- private AI summaries; -- account information; -- administrative actions; -- personal recommendations; -- sensitive workflow feedback without polluting the group timeline. - -### Agentic relevance - -**High.** - -This allows shared social spaces to contain private machine interactions without forcing users into a separate chat. - ---- - -# 5. Media Capabilities - -## MED-01 — Rich Media Messaging - -Telegram supports: - -- images; -- video; -- animation; -- audio; -- voice notes; -- video notes; -- arbitrary documents; -- stickers; -- GIFs; -- live photos; -- maps and locations; -- albums and grouped media. - -Bots can send and receive many of these media types. - ---- - -## MED-02 — Rich Messages - -The 2026 Bot API adds structured rich messages. - -Supported constructs include, among others: - -- headings; -- paragraphs; -- lists; -- tables; -- quotations; -- expandable sections; -- code/preformatted content; -- mathematical expressions; -- media; -- documents; -- maps; -- audio; -- images; -- video; -- buttons; -- references. - -### Agentic relevance - -**Very high.** - -Rich messages substantially improve Telegram as an output surface for: - -- research agents; -- reports; -- dashboards; -- comparisons; -- structured AI answers; -- approvals; -- operational summaries. - ---- - -## MED-03 — Live Response Streaming - -Bots can stream text while a response is being generated. - -### Uses - -- generative AI; -- search; -- analysis; -- long-running workflows; -- interactive research. - -### Agentic relevance - -**Core capability.** - -Streaming reduces the difference between a dedicated AI application and an AI service operating inside Telegram. - ---- - -# 6. Publishing Capabilities - -## PUB-01 — Channels - -Channels provide one-to-many publishing. - -### Characteristics - -- potentially unlimited subscriber audience; -- public or private; -- administrator roles; -- persistent post history; -- rich media; -- polls; -- stories; -- comments through linked discussion groups; -- direct messages to channel operators; -- subscriber interaction; -- analytics/statistics; -- monetization capabilities. - -### Suitable for - -- institutional publishing; -- news; -- product announcements; -- research publication; -- creator content; -- corporate communications. - -### Agentic relevance - -**High.** - -Agents can prepare, schedule, curate, moderate, and—in appropriately governed environments—publish content. - ---- - -## PUB-02 — Long-Form Rich Posts - -Telegram's 2026 rich-text editor allows long structured content. - -Capabilities include: - -- headings; -- lists; -- tables; -- quotes; -- inline media; -- generated text; -- formulas. - -Messages can extend substantially beyond conventional chat-message length. - -### Consequence - -Telegram increasingly overlaps with lightweight: - -- blogging; -- newsletters; -- documentation; -- knowledge publishing. - ---- - -## PUB-03 — Stories - -Telegram supports temporary story-style publishing. - -Possible uses include: - -- announcements; -- event coverage; -- informal updates; -- creator communication; -- live experiences. - ---- - -## PUB-04 — Public Discovery - -Public Telegram content can be discoverable through platform search. - -Relevant entities include: - -- users; -- channels; -- groups; -- bots; -- public posts. - -### Strategic implication - -Telegram is not only a subscribed-content medium. It increasingly provides **content discovery**. - ---- - -# 7. Community Capabilities - -## COM-01 — Community Composition - -Telegram introduced **Communities** as a mechanism for linking several: - -- groups; -- channels; -- bots. - -Members can access associated spaces through a coherent community entry. - -### Importance - -This creates an explicit organizational layer above individual chats. - -A conceptual model is: - -```text -Community -├── announcement channel -├── general group -├── specialist groups -├── project groups -├── event group -├── service bot -└── community agent -``` - -### Agentic relevance - -**Very high.** - -Communities create natural scopes for: - -- agent permissions; -- institutional identity; -- moderation; -- workflows; -- specialized service agents. - ---- - -## COM-02 — Membership Management - -Telegram provides: - -- private/public spaces; -- invite links; -- join requests; -- member permissions; -- administrator permissions; -- ownership; -- member removal; -- restrictions; -- approval workflows. - ---- - -## COM-03 — Moderation - -Native and bot-based moderation can include: - -- delete messages; -- restrict members; -- ban members; -- approve join requests; -- control media permissions; -- manage topics; -- manage tags; -- enforce community rules. - -Telegram has increasingly added AI-related moderation capabilities. - -### Architecture rule - -High-impact moderation should not depend solely on probabilistic model behavior. - -Recommended structure: - -```text -AI assessment - ↓ -policy decision - ↓ -deterministic enforcement layer - ↓ -Telegram API action -``` - ---- - -## COM-04 — Polls, Quizzes and Collective Decisions - -Telegram polls provide lightweight collective interaction. - -Uses: - -- community decisions; -- surveys; -- event planning; -- knowledge quizzes; -- feedback; -- agent-generated voting proposals. - ---- - -# 8. Bot Platform - -## BOT-01 — Bot Identity - -Bots are first-class Telegram accounts designed for software. - -They: - -- have usernames; -- have profiles; -- can receive messages; -- can send messages; -- can belong to groups; -- can administer groups/channels if authorized; -- do not require a phone number for normal bot creation. - -Bots execute application logic outside Telegram and communicate through Telegram APIs. - ---- - -## BOT-02 — Commands - -Bots may expose commands such as: - -```text -/start -/help -/search -/status -/approve -``` - -Commands can vary by chat context and user scope. - ---- - -## BOT-03 — Interactive Keyboards - -Bots support: - -- reply keyboards; -- inline keyboards; -- callback buttons; -- links; -- selectors; -- menus. - -These allow chat messages to behave like lightweight application interfaces. - ---- - -## BOT-04 — Inline Bots - -Bots can be invoked from the message field of other chats. - -Conceptually: - -```text -@agent query -``` - -This makes a service available without requiring users to leave their current conversation. - ---- - -## BOT-05 — Deep Linking - -Links can open: - -- bots; -- specific bot states; -- Mini Apps; -- group invitations; -- channels; -- other Telegram resources. - -Deep links enable Telegram to participate in external application workflows. - ---- - -## BOT-06 — Guest Bots - -Guest bots can answer invocations in chats even when they are not permanent members of those chats. - -### Agentic relevance - -This enables a useful pattern: - -```text -conversation - ↓ -invoke specialist agent - ↓ -temporary context access - ↓ -result -``` - -This reduces the need to permanently install every specialist bot into every group. - ---- - -## BOT-07 — Managed Bots - -Telegram supports programmatic creation and management of subordinate bots. - -### Agentic relevance - -**Extremely high.** - -Managed bots enable hierarchical agent architectures: - -```text -Agent Manager -├── Research Bot -├── Publishing Bot -├── Moderation Bot -├── Event Bot -└── Support Bot -``` - -A management system can create and administer specialized Telegram identities dynamically. - ---- - -## BOT-08 — Bot-to-Bot Communication - -Telegram supports direct coordination between bots. - -### Consequence - -Telegram can serve not only as a human-agent interaction surface but also as part of an **agent communication topology**. - -This should not automatically make Telegram the internal agent message bus; dedicated infrastructure may be more appropriate for high-volume or security-sensitive coordination. - ---- - -## BOT-09 — Business Bots - -Business accounts may delegate selected messaging capabilities to bots. - -### Uses - -- customer support; -- lead qualification; -- automated responses; -- workflow initiation; -- CRM integration; -- booking; -- commerce. - -### Governance requirement - -Delegated permissions should be explicit and minimal. - ---- - -# 9. Mini App Platform - -## APP-01 — Embedded Web Applications - -Telegram Mini Apps are HTML/JavaScript applications displayed inside Telegram. - -Telegram describes them as capable of replacing conventional websites for many workflows. - -### Capabilities - -- arbitrary web UI; -- Telegram identity; -- contextual launch; -- local/device storage; -- server integration; -- payment flows; -- push notifications; -- Telegram-aware navigation. - ---- - -## APP-02 — Application Authentication - -Mini Apps receive authenticated Telegram context. - -### Suitable for - -- personalized dashboards; -- account management; -- member portals; -- approvals; -- settings; -- workflow applications. - -### Security rule - -Telegram identity should usually be mapped to an internal canonical identity rather than used as the only authorization model. - -```text -Telegram identity - ↓ -identity mapping - ↓ -internal subject - ↓ -policy / authorization -``` - ---- - -## APP-03 — Application UX Extension - -Use a Mini App when chat interaction becomes awkward. - -Typical threshold: - -```text -conversation → Bot -simple choice → Buttons -structured form → Mini App -complex workflow → Mini App / external application -``` - ---- - -# 10. Identity Capabilities - -## ID-01 — Telegram User Identity - -Telegram provides stable platform identities associated with accounts. - -Relevant properties may include: - -- user ID; -- username; -- profile; -- display name; -- phone-number relationship where authorized. - -### Design rule - -Do not treat usernames as immutable identifiers. - -Use Telegram's numeric IDs for machine identity mapping. - ---- - -## ID-02 — Login with Telegram - -External applications can authenticate users through Telegram. - -Suitable for: - -- community portals; -- companion websites; -- membership applications; -- linked services. - ---- - -## ID-03 — Privacy-Preserving Contact - -Users can communicate without revealing their telephone number, depending on privacy configuration. - -This is important for public communities and creator/follower relationships. - ---- - -# 11. Business Capabilities - -## BUS-01 — Business Profiles - -Telegram Business accounts can expose: - -- opening hours; -- business location; -- customized start page; -- quick replies; -- greeting messages; -- away messages. - ---- - -## BUS-02 — Automated Customer Conversations - -Bots can be attached to business communication. - -Possible architecture: - -```text -Customer - ↓ -Telegram - ↓ -Business Bot - ↓ -CRM / workflow / agent - ↓ -Business policy - ↓ -response -``` - ---- - -## BUS-03 — Direct Customer Interaction - -Telegram can function as: - -- support channel; -- sales channel; -- account-management channel; -- notification channel; -- service-delivery channel. - ---- - -# 12. Commerce and Monetization - -## PAY-01 — Payments - -Bots and Mini Apps can support payment flows. - -Depending on transaction type and Telegram rules, payment mechanisms may involve: - -- external payment providers; -- platform-native payment mechanisms; -- Telegram Stars. - ---- - -## PAY-02 — Digital Goods - -Telegram Stars provide Telegram-native payment functionality for digital goods and services. - ---- - -## PAY-03 — Paid Content - -Possible models include: - -- paid media; -- paid channel access; -- paid subscriptions; -- premium services; -- creator monetization. - ---- - -## PAY-04 — Sponsored / Suggested Content - -Telegram provides mechanisms through which channels and creators can monetize audience reach. - -This can include: - -- sponsored content; -- suggested posts; -- advertising revenue models; -- affiliate-style mechanisms. - ---- - -# 13. Voice, Video and Live Interaction - -## RTC-01 — Voice Calls - -Telegram supports individual voice calling. - ---- - -## RTC-02 — Video Calls - -Telegram supports individual video calling and screen sharing. - ---- - -## RTC-03 — Group Calls - -Groups can host interactive voice/video sessions. - -Suitable for: - -- community meetings; -- office hours; -- events; -- discussions; -- presentations. - ---- - -## RTC-04 — Live Streaming - -Channels and other Telegram surfaces can support live broadcast-style interaction. - ---- - -# 14. Notification Capabilities - -## NOT-01 — Push Notifications - -Telegram provides cross-platform push delivery through its clients. - -This makes Telegram useful as a notification edge for external systems. - -Examples: - -```text -monitoring alert -build result -approval required -event reminder -community announcement -agent completion -security notification -``` - ---- - -## NOT-02 — User-Controlled Notification Policy - -Users retain significant control over notification behavior. - -Therefore: - -> Telegram delivery does not guarantee user attention. - -Applications requiring guaranteed acknowledgement should implement acknowledgement state externally. - ---- - -# 15. Integration Surfaces - -Telegram exposes several distinct integration surfaces. - -## INT-01 — Bot API - -HTTP API intended for bot applications. - -Best suited for: - -- chatbots; -- automation; -- notifications; -- community tools; -- agent interfaces; -- lightweight applications. - ---- - -## INT-02 — Mini App API - -JavaScript APIs for applications embedded inside Telegram. - -Best suited for: - -- forms; -- dashboards; -- account portals; -- commerce; -- complex interactions. - ---- - -## INT-03 — Telegram API / MTProto - -Provides lower-level access to Telegram's client capabilities. - -Best suited for: - -- custom clients; -- advanced integration; -- capabilities unavailable through the Bot API. - -This surface requires considerably more care than ordinary bot development. - ---- - -## INT-04 — TDLib - -Telegram Database Library provides an abstraction for building complete Telegram clients. - -Suitable for: - -- embedded Telegram clients; -- specialized Telegram applications; -- advanced automation requiring real user/client capabilities. - ---- - -## INT-05 — Web Login - -Telegram can provide identity/authentication to external web systems. - ---- - -# 16. Agentic Capability Model - -Telegram's 2026 feature set makes it useful to explicitly distinguish five agent roles. - -## AGT-01 — Conversational Agent - -```text -Human ↔ Agent -``` - -Examples: - -- assistant; -- advisor; -- support bot; -- knowledge agent. - ---- - -## AGT-02 — Group Participant Agent - -```text -Human -Human -Agent -Human -``` - -The agent participates in a shared social context. - -Examples: - -- community manager; -- moderator; -- researcher; -- facilitator. - ---- - -## AGT-03 — Guest Specialist Agent - -```text -Group - ↓ -invoke specialist - ↓ -Guest Bot -``` - -The agent enters the interaction only when needed. - ---- - -## AGT-04 — Delegated Operator Agent - -```text -Human owner - ↓ authority -Agent - ↓ -Telegram resources -``` - -The agent may: - -- answer messages; -- moderate; -- publish; -- manage workflows. - -This requires explicit policy boundaries. - ---- - -## AGT-05 — Multi-Agent System - -```text -Coordinator -├── Research Agent -├── Publishing Agent -├── Moderator -├── Concierge -└── Operations Agent -``` - -Telegram now contains primitives supporting bot-to-bot communication and managed bots. - -Telegram can therefore expose a multi-agent system directly to users. - ---- - -# 17. Security Model - -## SEC-01 — Cloud Chats - -Ordinary Telegram cloud chats are encrypted in transit/client-server architecture but are not end-to-end encrypted in the same way as Secret Chats. - -This distinction is important for security-sensitive systems. - ---- - -## SEC-02 — Secret Chats - -Secret Chats provide device-specific end-to-end encrypted communication. - -They are fundamentally different from cloud chats and have different automation properties. - -### Agentic limitation - -Secret Chats are not a general-purpose bot interaction environment. - ---- - -## SEC-03 — Account Security - -Telegram supports mechanisms such as: - -- two-step verification; -- passkeys; -- device/session management; -- local application locks; -- privacy controls. - ---- - -## SEC-04 — Bot Credentials - -Bot API tokens are security credentials. - -Treat them as secrets. - -Required controls should include: - -- secret manager storage; -- rotation; -- least access; -- audit; -- environment isolation; -- revocation procedures. - -Never embed production bot tokens in source code. - ---- - -# 18. Governance Rules for Agentic Telegram Systems - -Telegram permits significant automation, but platform capability should not be confused with governance. - -Recommended architecture: - -```text - Agent / LLM - │ - ▼ - proposed action - │ - ▼ - deterministic policy - │ - ┌──────┴──────┐ - │ │ - denied allowed - │ - ▼ - Telegram Adapter - │ - ▼ - Telegram -``` - -## Core principles - -### G-01 — Deterministic authority - -Permissions, credential scope, and irreversible operations should be enforced by deterministic systems. - -### G-02 — Least privilege - -Each bot or agent should receive only the Telegram permissions required for its role. - -### G-03 — Separation of identities - -Prefer distinct bot identities for materially different responsibilities. - -### G-04 — External source of truth - -Important operational state should normally be persisted outside Telegram. - -### G-05 — Auditability - -Agent-initiated actions should carry sufficient metadata to reconstruct: - -- who initiated the action; -- which agent executed it; -- which policy authorized it; -- what Telegram action occurred; -- what result was returned. - -### G-06 — Bounded autonomy - -Autonomous agents should have explicit limits for: - -- publishing; -- deleting; -- banning; -- payment operations; -- membership changes; -- credential management. - ---- - -# 19. Telegram as an Edge Architecture - -For sophisticated systems, Telegram is best modeled as an **interaction edge**. - -```text - Telegram - │ - telegram-edge - │ - ┌───────────┼───────────┐ - │ │ │ - Identity Workflow Agents - │ │ │ - └───────────┼───────────┘ - │ - Core Systems -``` - -`telegram-edge` should normally own: - -- webhook/API integration; -- Telegram identity mapping; -- Telegram entity mapping; -- message normalization; -- outbound rendering; -- Telegram permission translation; -- retry handling; -- rate-limit handling; -- audit correlation; -- attachment handling; -- deep links; -- Mini App launch integration. - -It should **not** become the canonical store for business logic that belongs elsewhere. - ---- - -# 20. Canonical Telegram Entity Model - -A useful normalized model is: - -```text -TelegramPlatform -│ -├── User -├── Bot -│ -├── Chat -│ ├── PrivateChat -│ ├── Group -│ │ └── Topic -│ └── Channel -│ -├── Community -│ └── Chat references -│ -├── Message -│ ├── Content -│ ├── Media -│ ├── RichMessage -│ └── Interaction -│ -├── MiniApp -│ -├── Call / LiveSession -│ -├── Payment -│ -└── Membership / Permission -``` - ---- - -# 21. Capability Selection Guide - -| Requirement | Preferred Telegram Primitive | -|---|---| -| Private conversation | Private chat | -| Announcement publishing | Channel | -| Open discussion | Group | -| Structured discussion | Group + Topics | -| Multi-space institution | Community | -| Interactive automation | Bot | -| AI assistant | Bot + streaming/rich messages | -| Specialist invoked anywhere | Guest Bot / Inline Bot | -| Complex interface | Mini App | -| Customer automation | Business Bot | -| Event/live discussion | Group Call / Live Stream | -| Payments | Bot / Mini App + payment capability | -| Human + multiple agents | Community + Bots | -| External authentication | Login with Telegram | -| Full custom Telegram client | TDLib / Telegram API | - ---- - -# 22. Coulomb Society Reference Pattern - -A possible Telegram-native structure for the Coulomb Society is: - -```text -Coulomb Society Community -│ -├── Coulomb Society Channel -│ └── official publishing -│ -├── Society Commons -│ └── general discussion -│ -├── Research Forum -│ ├── Physics -│ ├── Technology -│ ├── Arts -│ └── Philosophy -│ -├── Events -│ └── meetings / lectures / live sessions -│ -├── Charles-Augustin de Coulomb Sp. -│ └── community manager / concierge -│ -├── Research Agents -│ └── specialist guest bots -│ -└── Society Mini App - ├── membership - ├── profile - ├── events - ├── projects - └── contribution workflows -``` - -The important architectural distinction is: - -> The **Society exists independently of Telegram**; Telegram is the primary social and communication surface through which the Society is experienced. - -This keeps future federation or expansion to other surfaces possible. - ---- - -# 23. Capability Maturity Model - -For platform planning, capabilities can be scored: - -| Stage | Description | -|---|---| -| **T0 — Manual** | Humans operate Telegram manually. | -| **T1 — Assisted** | Bots provide commands and notifications. | -| **T2 — Integrated** | Telegram is connected to external services. | -| **T3 — Workflow** | Business/community workflows execute through Telegram. | -| **T4 — Agent Assisted** | Agents prepare actions; humans approve. | -| **T5 — Bounded Autonomous** | Agents execute within deterministic policy boundaries. | -| **T6 — Adaptive Multi-Agent** | Multiple specialized agents coordinate while governance remains deterministic. | - -The goal should generally not be maximum maturity everywhere. - -Each capability should advance only as far as its risk, value, observability, and reversibility justify. - ---- - -# 24. Telegram Strengths - -Telegram is particularly strong where a system needs several of the following simultaneously: - -- human messaging; -- public publishing; -- large communities; -- notifications; -- programmable bots; -- embedded applications; -- identity; -- payments; -- media; -- AI interaction; -- mobile and desktop availability; -- low-friction onboarding. - -This combination is unusual. - ---- - -# 25. Telegram Weaknesses and Boundaries - -Telegram should not automatically be used as: - -- a canonical enterprise database; -- a high-assurance authorization system; -- a durable workflow engine; -- a general event bus; -- a secret-management system; -- a regulated document archive; -- a guaranteed-delivery notification system; -- an internal high-volume agent coordination backbone. - -These responsibilities normally belong to external infrastructure. - -Telegram should expose them through interaction adapters. - ---- - -# 26. Strategic Interpretation - -Telegram can be understood as: - -> **A globally deployed interaction runtime combining identity, messaging, publishing, communities, applications, payments, and increasingly first-class human/agent collaboration.** - -Its strategic value is therefore larger than its conventional classification as a messaging application suggests. - -For agent-active systems, the most significant capabilities are increasingly: - -```text -identity -+ conversation -+ community context -+ rich output -+ streaming -+ embedded applications -+ delegated bots -+ guest agents -+ bot-to-bot communication -+ deterministic external governance -``` - -Together these allow Telegram to become a practical **social edge for agentic systems**. - ---- - -# 27. Reference Architecture Principle - -The canonical integration rule for systems built around Telegram should be: - -> **Telegram owns interaction. The application owns truth. The policy layer owns authority. Agents own bounded interpretation and action.** - -Expressed architecturally: - -```text -Telegram - │ - ▼ -Interaction Edge - │ - ▼ -Identity / Context - │ - ▼ -Agent or Application - │ - ▼ -Deterministic Policy - │ - ▼ -Domain Systems -``` - -This separation enables sophisticated Telegram-native experiences without making the security, consistency, or longevity of the system dependent on Telegram itself. - ---- - -# 28. Sources - -Primary Telegram documentation consulted for this version: - -1. Telegram Bot Platform — Introduction - https://core.telegram.org/bots - -2. Telegram Bot Features - https://core.telegram.org/bots/features - -3. Telegram Bot API - https://core.telegram.org/bots/api - -4. Telegram Bot API Changelog - https://core.telegram.org/bots/api-changelog - -5. Telegram Mini Apps - https://core.telegram.org/bots/webapps - -6. Telegram API — Bots - https://core.telegram.org/api/bots - -7. Telegram AI Features for Bots - https://core.telegram.org/api/bots/ai - -8. Telegram Blog — Communities and Rich Text, July 2026 - https://telegram.org/blog/communities-editor-invisible-messages - -9. Telegram Business - https://telegram.org/blog/telegram-business - ---- - -# 29. Canon Maintenance - -Telegram evolves quickly. - -This document should therefore distinguish: - -- **canonical concepts**, which should remain stable; -- **Telegram implementations**, which may change; -- **limits and commercial terms**, which should be periodically revalidated. - -Recommended update triggers: - -- major Bot API releases; -- new identity or authorization models; -- new community abstractions; -- changes to payment rules; -- significant agent/AI capabilities; -- material changes to API limits; -- changes affecting privacy or security architecture. - ---- - -**End of Telegram Capability Canon v0.1** diff --git a/contracts/r1.openapi.yaml b/contracts/r1.openapi.yaml deleted file mode 100644 index b38d34d..0000000 --- a/contracts/r1.openapi.yaml +++ /dev/null @@ -1,103 +0,0 @@ -openapi: "3.1.0" -info: - title: HelixForge Telegram Publishing - version: "R-1" - description: | - Publishes hall-of-helix entries to a Telegram channel. - - The interface takes an entry as it was written and is responsible for - everything about how it becomes a Telegram post. A caller should never need - to know Telegram's constraints. - - Publication is idempotent on entry_id: publishing the same entry twice - yields one publication. This matters because the caller is usually - automation that may be retried. - -paths: - /v1/hall-entries: - post: - operationId: publishEntry - summary: Publish a hall-of-helix entry - requestBody: - required: true - content: - application/json: - schema: - type: object - required: [entry_id, title, body] - additionalProperties: false - properties: - entry_id: - type: string - minLength: 1 - maxLength: 128 - description: | - The hall entry's own id, from its frontmatter. Publication - is idempotent on this value. - title: - type: string - minLength: 1 - maxLength: 256 - body: - type: string - minLength: 1 - description: | - The entry body as Markdown, frontmatter removed. - - Deliberately unbounded. Telegram's 4096-character message - limit is this interface's problem, not the caller's, and a - maxLength here would push it back onto them. - display_name: - type: string - maxLength: 128 - worker_kind: - type: string - enum: [human, agent-session] - recorded_at: - type: string - format: date - source_url: - type: string - description: Canonical location of the entry in hall-of-helix. - responses: - "201": - description: Published - "200": - description: Already published; the existing publication is returned - "400": - description: The entry cannot be published faithfully - "502": - description: Telegram was unreachable or refused the message - - get: - operationId: listPublications - summary: List publications, newest first - parameters: - - name: limit - in: query - required: false - schema: {type: integer, minimum: 1, maximum: 100} - - name: state - in: query - required: false - schema: - type: string - enum: [pending, published, failed, superseded] - responses: - "200": - description: Publications - - /v1/hall-entries/{entry_id}: - get: - operationId: getPublication - summary: Publication state for one entry - parameters: - - name: entry_id - in: path - required: true - schema: {type: string, minLength: 1} - responses: - "200": - description: Publication state - "404": - description: This entry has not been published diff --git a/docs/adapter-contract.md b/docs/adapter-contract.md deleted file mode 100644 index 74a53e5..0000000 --- a/docs/adapter-contract.md +++ /dev/null @@ -1,100 +0,0 @@ -# Telegram adapter — connector capability contract - -The adapter is an ordinary HTTP service. fluid-core sits in front of it and -asks nothing of it beyond the endpoints below, so it may be written in whatever -suits the platform — grammY on Node is the obvious choice for the Telegram Bot -API. - -## What the adapter owns - -- Rendering a hall entry into Telegram's message forms. -- Talking to the Telegram Bot API. -- Custody of the bot token for the duration of a call. -- Idempotency: recognising an `entry_id` it has already published. - -## What the adapter must not do - -- Create, rename or delete channels, groups or bots. -- Change membership, administrators or permissions. -- Post to any chat other than the one it is configured with. -- Edit entry content to make it fit. If an entry cannot be published - faithfully, refuse it — that refusal is the pressure signal. -- Log, echo or forward the bot token, including in error messages. - -## Endpoints - -Exactly the three operations in `contracts/r1.openapi.yaml`, at the same paths. -The gateway validates requests against that contract before the adapter sees -them, so the adapter may assume shape but must still assume hostile content. - -## Backend capability contract - -| Property | Value | -|---|---| -| Backend identity | Telegram Bot API (`api.telegram.org`) | -| Authentication | Bot token, injected at start from OpenBao; never in the image | -| Timeout | 30s per Telegram call | -| Retry | On 429 only, honouring `retry_after`. Never retry a `sendMessage` that may have succeeded | -| Circuit breaker | 5 consecutive failures opens for 60s | -| Rate limits | ~20 messages/minute to a channel; ~30 requests/second overall | -| Error mapping | 429 → 502 with `retry_after` preserved; 400 → 400; network failure → 502 | -| Tenant propagation | None; single tenant | - -## The idempotency requirement - -`POST /v1/hall-entries` is idempotent on `entry_id`. The caller is automation -that may be retried, and a duplicate hall entry in the channel is not something -you can quietly undo — subscribers have already seen it. - -The adapter keeps its own mapping from `entry_id` to the Telegram message ids it -produced. On a repeat call it returns `200` with the existing publication rather -than posting again. If the entry content has changed, it edits the existing -messages rather than posting new ones. - -This state is the adapter's, not fluid-core's. The evidence store records that a -publication happened; the adapter records which Telegram messages implement it. - -## Rendering rules - -Telegram formatting is not Markdown. Entry Markdown must be converted, not -passed through. - -| Entry construct | Telegram | -|---|---| -| `# Heading` | Bold line | -| `**bold**`, `_italic_` | ``, `` in HTML parse mode | -| Fenced code | `
` |
-| Tables | Flattened to lines; Telegram has no table |
-| Links | `` |
-| Frontmatter | Stripped; `display_name` and `recorded_at` surfaced in the header |
-
-Anything the converter cannot represent faithfully must fail the publication
-rather than degrade it silently. `entry_content_loss` is a hard guardrail in
-both competing hypotheses, and it can only be honest if the adapter refuses
-rather than approximates.
-
-## Telemetry the adapter should emit
-
-The gateway observes the request path already. The adapter adds what only it can
-see, by POSTing to the control plane's `/control/v1/telemetry`:
-
-- `messages_per_entry` — how many Telegram messages one entry became.
-- `entry_content_loss` — whether the conversion dropped anything.
-- Telegram rate-limit encounters, as error events with class `backend_failure`.
-
-It must not emit subscriber identity in any form. Engagement metrics
-(`read_through_rate`, `reaction_rate`) come from Telegram's channel statistics
-as aggregates, never per-reader.
-
-## Configuration
-
-| Variable | Meaning |
-|---|---|
-| `TELEGRAM_BOT_TOKEN` | Injected from OpenBao at start |
-| `TELEGRAM_CHANNEL_ID` | The channel this adapter publishes to |
-| `FLUID_CONTROL_URL` | Where to POST telemetry |
-| `HALL_BASE_URL` | Base URL for links back to hall-of-helix |
-
-One adapter instance serves one channel. The private test channel and the public
-channel are separate instances with separate configuration, which is what keeps
-a test publication from reaching subscribers by accident.
diff --git a/docs/observation.md b/docs/observation.md
deleted file mode 100644
index 21b2928..0000000
--- a/docs/observation.md
+++ /dev/null
@@ -1,70 +0,0 @@
-# Cohorts, telemetry and redaction
-
-## Cohorts
-
-Four populations, deliberately coarse. Blueprint §6.3 asks for cohorts stable
-enough to compare over time and no more granular than the analysis requires.
-
-| Cohort | Assigned by | Why it is distinct |
-|---|---|---|
-| `hall-publishing-jobs` | `X-FLUID-Consumer` prefix `hall-` | Batch behaviour; publishes many entries at once |
-| `helix-forge-agents` | `X-FLUID-Consumer` prefix `agent-` | One entry at a time, at session end; the richest pressure signal |
-| `operators` | `X-FLUID-Consumer` prefix `op-` | Rare, deliberate, often corrective |
-| `telegram-subscribers` | Not a caller | An observed population, never an API consumer |
-
-`telegram-subscribers` deserves care. It appears in experiment allocation and in
-engagement metrics, but it never authenticates and never appears as
-`ConsumerRef`. Treating readers as consumers would be the first step toward
-observing them individually.
-
-## Redaction
-
-```
-CohortMinimumSize: 5
-RetentionDays:     365
-AllowRawPayload:   false
-```
-
-Beyond the fluid-core defaults, this interface adds:
-
-- **No Telegram user identity, ever.** Canon ID-01 identities — user ids,
-  usernames, display names of subscribers — must not reach the evidence store
-  in any form, redacted or otherwise. There is no legitimate analysis that
-  needs them, so the safe rule is that they never arrive.
-- **Entry content is not telemetry.** An entry body may appear in a request; it
-  must not appear in a telemetry event. What is recorded is its length, its
-  section count, and whether conversion succeeded.
-- **The bot token appears nowhere.** Not in errors, not in traces, not in
-  redacted form.
-
-## The pseudonymization salt
-
-Generate once, store in OpenBao alongside the bot token, inject as
-`FLUID_REDACTION_SALT`:
-
-```bash
-openssl rand -hex 32
-```
-
-It must never change. Rotating it makes every previously-seen consumer look
-new, which silently invalidates every longitudinal comparison the interface has
-accumulated. If it is ever compromised, the correct response is to accept the
-loss and start a fresh evidence baseline, not to rotate quietly.
-
-## Metrics
-
-| Metric | Role | Source |
-|---|---|---|
-| `read_through_rate` | primary | Telegram channel statistics, aggregate |
-| `messages_per_entry` | guardrail | Adapter |
-| `entry_content_loss` | guardrail | Adapter |
-| `error_rate` | guardrail | Gateway |
-| `reaction_rate` | secondary | Telegram channel statistics, aggregate |
-| `time_to_first_read` | learning | Telegram channel statistics, aggregate |
-
-`read_through_rate` is the one to be careful about. Telegram reports view counts
-per message, not per reader. For the teaser form it is link clicks over views;
-for the serialized form it is views of the last part over views of the first.
-Those are not the same measurement, and comparing them directly is the weakest
-part of the first experiment. Say so in the experiment's amendment record rather
-than letting the comparison look cleaner than it is.
diff --git a/docs/runbook.md b/docs/runbook.md
deleted file mode 100644
index adf5ed7..0000000
--- a/docs/runbook.md
+++ /dev/null
@@ -1,76 +0,0 @@
-# Runbook — helix-forge-telegram-publishing
-
-## Rotating the bot token
-
-1. In BotFather: `/revoke` for the bot, which issues a new token.
-2. Write the new token to OpenBao at the interface's secret path.
-3. Restart the adapter. It reads the token at start only.
-4. Confirm with one publication to the **private test channel**.
-
-The old token stops working the moment it is revoked, so publications in flight
-will fail. Do this when nothing is publishing.
-
-## Recovering channel administration
-
-If the bot loses its administrator rights, it cannot post and every publication
-fails with a Telegram `400`.
-
-1. In the channel's administrator settings, confirm the bot is present with
-   **Post Messages** enabled.
-2. Grant nothing else. The bot does not need to edit others' messages, delete
-   messages, or manage members, and the intent forbids it from using such
-   rights if it had them.
-3. If the bot was removed entirely, re-add it and re-run one test publication.
-
-A human must do this. The Daimon is forbidden from changing channel membership
-or permissions (`InterfaceEvolutionIntent.md` §7).
-
-## Rolling back a revision
-
-Publish a routing policy with a higher generation naming the previous revision
-as default:
-
-```bash
-fluid experiment stop  --generation N --default-revision R-1 \
-  --reason "..." --policy-out rollback.json
-fluid policy put --file rollback.json
-```
-
-If no experiment is running, write the policy by hand with `default_revision`
-set to the known-good revision and a generation above the current one. Rollback
-is a document replacement; nothing is unwound.
-
-Already-published Telegram messages are **not** rolled back. They were seen.
-Correcting a published entry is an edit through the adapter, not a rollback.
-
-## An entry published wrongly
-
-1. Stop further publication: install a policy pointing at the last known-good
-   revision.
-2. Correct the entry in `hall-of-helix` and re-publish it. The adapter edits the
-   existing messages rather than posting new ones.
-3. If the entry cannot be corrected in place — wrong entry entirely, or content
-   that should not have been published — delete the messages by hand in
-   Telegram and record why in the publication's audit trail.
-4. Record a pressure observation. An entry published wrongly is exactly the
-   evidence the framework exists to collect, and the instinct to tidy it away
-   is the instinct to lose it.
-
-## Checking what happened
-
-```bash
-export FLUID_INTERFACE=helix-forge-telegram-publishing
-
-fluid audit trace R-1            # how a revision came to exist, and what followed
-fluid pressure list              # what the interface is currently struggling with
-fluid telemetry --limit 50       # recent traffic
-fluid events --entity  # one publication's history
-```
-
-## When the evidence store is unavailable
-
-Publication continues. The gateway serves from cached configuration and buffers
-telemetry, dropping it if the buffer fills. You lose observation, not service.
-
-Do not promote anything while the store is down: the promotion would be
-unauditable, which is the one thing this framework will not trade away.
diff --git a/experiments/E-tg-length.yaml b/experiments/E-tg-length.yaml
deleted file mode 100644
index 472b352..0000000
--- a/experiments/E-tg-length.yaml
+++ /dev/null
@@ -1,68 +0,0 @@
-# The first live experiment: which presentation serves readers better.
-#
-# Do not start this until the private test channel has confirmed both forms
-# render correctly, and the public channel has enough subscribers for the
-# result to mean anything. The intent (section 12) is explicit that an
-# underpowered window should report INCONCLUSIVE rather than be shortened.
-#
-#   fluid experiment design --file experiments/E-tg-length.yaml
-#   fluid experiment start E-tg-length --generation 2 \
-#     --default-revision R-2 --policy-out rp.json
-#   fluid policy put --file rp.json
-fluid_experiment:
-  schema_version: "0.1"
-
-  id: "E-tg-length"
-  interface_id: "helix-forge-telegram-publishing"
-
-  hypothesis_refs:
-    - "H-tg-teaser"
-    - "H-tg-serial"
-
-  # R-2 implements the teaser form, R-3 the serialized form. Neither is the
-  # control in the usual sense: R-1 cannot publish a long entry at all, so
-  # this is a comparison between two answers rather than against a baseline.
-  control_revision: "R-2"
-  candidate_revisions:
-    - "R-3"
-
-  cohorts:
-    - "telegram-subscribers"
-
-  allocation:
-    control: 0.5
-    candidate: 0.5
-
-  # An even split because there is no incumbent to protect. The usual 90/10
-  # caution exists to limit exposure to an unproven candidate; here both arms
-  # are equally unproven and the scarce resource is entries, not safety.
-
-  metrics:
-    primary:
-      - "read_through_rate"
-    guardrails:
-      - "entry_content_loss"
-      - "error_rate"
-      - "messages_per_entry"
-    secondary:
-      - "reaction_rate"
-      - "forward_rate"
-    learning:
-      - "time_to_first_read"
-
-  start_conditions:
-    - "both revisions verified against the private test channel"
-    - "channel has at least 100 subscribers"
-
-  stop_conditions:
-    - "hard_guardrail_violation"
-    - "entry_content_loss"
-    - "manual_stop"
-    - "max_duration_reached"
-
-  max_duration_hours: 2160  # 90 days: roughly 12 entries at current cadence
-
-  result:
-    state: "PLANNED"
-    preferred_revision: null
-    evidence_refs: []
diff --git a/hypotheses/H-tg-serial.yaml b/hypotheses/H-tg-serial.yaml
deleted file mode 100644
index 57b6aa7..0000000
--- a/hypotheses/H-tg-serial.yaml
+++ /dev/null
@@ -1,125 +0,0 @@
-# Competing hypothesis B, in group CG-tg-length.
-fluid_hypothesis:
-  schema_version: "0.1"
-
-  id: "H-tg-serial"
-  interface_id: "helix-forge-telegram-publishing"
-  state: "DRAFT"
-
-  title: "The whole entry in the channel serves readers better than a link"
-
-  observation:
-    summary: >
-      85% of hall entries exceed Telegram's 4096-character message limit, with
-      a median body of 5767 characters. The interface must choose a form for
-      long entries before it can publish at all.
-    evidence_refs:
-      - "measurement:hall-of-helix/entries@2026-09-04"
-      - "pressure:P-tg-length"
-    affected_cohorts:
-      - "telegram-subscribers"
-
-  pressure:
-    classes:
-      - "missing_interface_capability"
-    pressure_refs:
-      - "P-tg-length"
-    severity: 0.85
-    confidence: 1.0
-
-  explanation:
-    claim: >
-      A link out of Telegram is a cost most readers will not pay. Telegram's
-      rich-text posts are built for long-form reading and the audience is
-      already there. Serializing the entry across a small number of linked
-      messages keeps the whole account where the reader is, and the median
-      entry needs only two.
-    reach:
-      score: 0.5
-      explains:
-        - "P-tg-length"
-      notes: >
-        Medium reach. It answers the length constraint natively but does not
-        transfer to platforms with harder limits.
-
-  proposed_adaptation:
-    class: "presentation"
-    summary: >
-      Split the entry at section boundaries into a small number of rich-text
-      messages, each linked to the previous, with the visual attached to the
-      first.
-    implementation_scope: "interface_only"
-
-  backend_requirements:
-    required: false
-    requirement_refs: []
-
-  expected_outcomes:
-    - metric: "read_through_rate"
-      cohort: "telegram-subscribers"
-      target: 0.15
-      direction: "higher"
-    - metric: "messages_per_entry"
-      cohort: "all"
-      baseline: 1.0
-      target: 2.0
-      direction: "higher"
-
-  guardrails:
-    - metric: "entry_content_loss"
-      operator: "=="
-      threshold: false
-    - metric: "error_rate"
-      operator: "<="
-      threshold: 0.01
-    - metric: "messages_per_entry"
-      operator: "<="
-      threshold: 4
-
-  fitness_dimensions:
-    expected:
-      client_utility: 0.5
-      discoverability: 0.3
-      simplicity: -0.2
-      correctness: 0.0
-      security: 0.0
-
-  complexity:
-    expected_delta:
-      operation_count: 0
-      concept_count: 1
-      alternative_path_count: 1
-      cognitive_load: 0.2
-    score: 0.3
-
-  risk:
-    level: "LOW"
-    reasons:
-      - "presentation only"
-      - "splitting can lose meaning at a bad boundary; guarded by content-loss check"
-
-  economics:
-    estimated_experiment_cost: 0.0
-    estimated_implementation_cost: 0.0
-    currency: "EUR"
-    expected_value_class: "MEDIUM"
-
-  learning_value:
-    score: 0.8
-    notes: >
-      Tests whether an audience will read long-form in place, which is the
-      question behind every publishing interface HelixForge will build.
-
-  success_criteria:
-    expression: >
-      read_through_rate >= 0.15 AND messages_per_entry <= 4 AND no guardrail violation
-
-  failure_criteria:
-    expression: >
-      any hard guardrail violation
-      OR read_through_rate below the teaser alternative over the same window
-
-  outcome:
-    status: null
-    summary: null
-    evidence_refs: []
diff --git a/hypotheses/H-tg-teaser.yaml b/hypotheses/H-tg-teaser.yaml
deleted file mode 100644
index bd7db11..0000000
--- a/hypotheses/H-tg-teaser.yaml
+++ /dev/null
@@ -1,125 +0,0 @@
-# Competing hypothesis A, in group CG-tg-length.
-#
-# Create with:
-#   fluid hypothesis create --file hypotheses/H-tg-teaser.yaml
-#   fluid hypothesis compete --group CG-tg-length H-tg-teaser H-tg-serial
-fluid_hypothesis:
-  schema_version: "0.1"
-
-  id: "H-tg-teaser"
-  interface_id: "helix-forge-telegram-publishing"
-  state: "DRAFT"
-
-  title: "A teaser and a link serve readers better than the whole entry"
-
-  observation:
-    summary: >
-      85% of hall entries exceed Telegram's 4096-character message limit, with
-      a median body of 5767 characters. The interface must choose a form for
-      long entries before it can publish at all.
-    evidence_refs:
-      - "measurement:hall-of-helix/entries@2026-09-04"
-      - "pressure:P-tg-length"
-    affected_cohorts:
-      - "telegram-subscribers"
-
-  pressure:
-    classes:
-      - "missing_interface_capability"
-    pressure_refs:
-      - "P-tg-length"
-    severity: 0.85
-    confidence: 1.0
-
-  explanation:
-    claim: >
-      A channel post is scanned, not read. A hall entry is a considered
-      first-person account that rewards attention. Presenting an opening and a
-      link lets a reader decide to give it that attention somewhere designed
-      for reading, rather than committing to a wall of text in a feed.
-    reach:
-      score: 0.5
-      explains:
-        - "P-tg-length"
-      notes: >
-        Medium reach. It answers the length constraint and would answer the
-        same constraint on X, but it does not address entries with visuals or
-        entries readers might want to keep in the channel.
-
-  proposed_adaptation:
-    class: "presentation"
-    summary: >
-      Publish the title, the display name, the opening of the entry, and a link
-      to the full entry in hall-of-helix.
-    implementation_scope: "interface_only"
-
-  backend_requirements:
-    required: false
-    requirement_refs: []
-
-  expected_outcomes:
-    - metric: "read_through_rate"
-      cohort: "telegram-subscribers"
-      target: 0.15
-      direction: "higher"
-    - metric: "messages_per_entry"
-      cohort: "all"
-      baseline: 2.0
-      target: 1.0
-      direction: "lower"
-
-  guardrails:
-    - metric: "entry_content_loss"
-      operator: "=="
-      threshold: false
-    - metric: "error_rate"
-      operator: "<="
-      threshold: 0.01
-
-  fitness_dimensions:
-    expected:
-      client_utility: 0.4
-      discoverability: 0.5
-      simplicity: 0.6
-      correctness: 0.0
-      security: 0.0
-
-  complexity:
-    expected_delta:
-      operation_count: 0
-      concept_count: 0
-      cognitive_load: -0.1
-    score: 0.05
-
-  risk:
-    level: "LOW"
-    reasons:
-      - "presentation only; no contract or authorization change"
-      - "fully reversible by replacing the revision"
-
-  economics:
-    estimated_experiment_cost: 0.0
-    estimated_implementation_cost: 0.0
-    currency: "EUR"
-    expected_value_class: "MEDIUM"
-
-  learning_value:
-    score: 0.8
-    notes: >
-      Whichever way this resolves, the answer transfers directly to
-      fluid-x and fluid-substack, which face the same problem under
-      different constraints.
-
-  success_criteria:
-    expression: >
-      read_through_rate >= 0.15 AND no guardrail violation
-
-  failure_criteria:
-    expression: >
-      any hard guardrail violation
-      OR read_through_rate below the serialized alternative over the same window
-
-  outcome:
-    status: null
-    summary: null
-    evidence_refs: []
diff --git a/pressure/P-length-limit.yaml b/pressure/P-length-limit.yaml
deleted file mode 100644
index bef081f..0000000
--- a/pressure/P-length-limit.yaml
+++ /dev/null
@@ -1,47 +0,0 @@
-# Seed pressure record.
-#
-# This is not derived from telemetry. It is a structural constraint measured
-# directly against hall-of-helix on 2026-09-04, and it is real before the
-# interface has served a single request. The intent (section 13) permits a
-# structural constraint to found a hypothesis without waiting for repetition.
-#
-# Record it with:
-#   fluid pressure ... (or let the first classification pass confirm it)
-fluid_pressure:
-  schema_version: "0.1"
-
-  id: "P-tg-length"
-  interface_id: "helix-forge-telegram-publishing"
-
-  class: "missing_interface_capability"
-
-  first_seen: "2026-09-04T00:00:00Z"
-  last_seen: "2026-09-04T00:00:00Z"
-
-  affected_cohorts:
-    - "hall-publishing-jobs"
-    - "helix-forge-agents"
-
-  frequency:
-    observations: 80
-    independent_consumers: 2
-
-  severity: 0.85
-  confidence: 1.0
-
-  summary: >
-    Telegram limits a single message to 4096 characters. Of the 94 entries in
-    hall-of-helix on 2026-09-04, 80 have bodies exceeding that limit — 85%.
-    The median body is 5767 characters and the largest is 10220. No entry of
-    typical length can be published as one message, so the interface cannot
-    fulfil its mission without deciding how a long entry becomes a post.
-
-  evidence_refs:
-    - "measurement:hall-of-helix/entries@2026-09-04"
-    - "canon:fluid-telegram/TelegramCapabilityCanon.md#PUB-02"
-
-  status: "ANALYZING"
-
-  linked_hypotheses:
-    - "H-tg-teaser"
-    - "H-tg-serial"
diff --git a/revisions/R-1.yaml b/revisions/R-1.yaml
deleted file mode 100644
index 3486d9d..0000000
--- a/revisions/R-1.yaml
+++ /dev/null
@@ -1,52 +0,0 @@
-# Revision descriptor for R-1.
-#
-# Fill in the digest and upstream, then publish through the pipeline:
-#
-#   fluid revision publish --file revisions/R-1.yaml \
-#     --key-file "$FLUID_SIGNING_KEY" \
-#     --adaptation-classes presentation \
-#     --approved-by "$USER" --traffic-share 1.0
-#
-# The digest is the sha256 of contracts/r1.openapi.yaml:
-#   printf 'sha256:%s' "$(sha256sum contracts/r1.openapi.yaml | cut -d' ' -f1)"
-revision:
-  schema_version: "0.1"
-  id: "R-1"
-  interface: "helix-forge-telegram-publishing"
-  state: "stable"
-
-  contract:
-    type: "openapi"
-    digest: "sha256:"
-    source: "contracts/r1.openapi.yaml"
-
-  runtime:
-    upstream: "http://fluid-telegram-adapter:8080"
-    # Telegram rate-limits channel posts to roughly 20 per minute. A generous
-    # timeout is correct here: publication is not latency-sensitive, and
-    # failing fast would turn a rate limit into a lost entry.
-    timeout_ms: 30000
-    retry:
-      # Only GET is retried by the connector; POST /v1/hall-entries is
-      # idempotent on entry_id, but the retry decision stays with the adapter,
-      # which knows whether Telegram accepted the message.
-      max_attempts: 1
-    circuit_breaker:
-      failure_threshold: 5
-      reset_after_ms: 60000
-
-  intent:
-    version: "IEI-1"
-
-  routing:
-    eligible_cohorts:
-      - "hall-publishing-jobs"
-      - "helix-forge-agents"
-      - "operators"
-    max_traffic_share: 1.0
-
-  policy:
-    compatibility: "additive"
-    security_check: "passed"
-    policy_check: "passed"
-    rollback_to: null
diff --git a/workplans/FLUID-WP-0001-statehub-bootstrap.md b/workplans/FLUID-WP-0001-statehub-bootstrap.md
deleted file mode 100644
index 151c552..0000000
--- a/workplans/FLUID-WP-0001-statehub-bootstrap.md
+++ /dev/null
@@ -1,59 +0,0 @@
----
-id: FLUID-WP-0001
-type: workplan
-title: "Bootstrap State Hub integration"
-domain: infotech
-repo: fluid-telegram
-status: ready
-owner: codex
-topic_slug: custodian
-created: "2026-09-04"
-updated: "2026-09-04"
-state_hub_workstream_id: "b5c231e1-9d06-5772-95a7-01cc0bf62051"
----
-
-# Bootstrap State Hub integration
-
-Fluid interface for telegram messaging and interaction platform.
-
-## Review Generated Integration Files
-
-```task
-id: FLUID-WP-0001-T01
-status: todo
-priority: high
-state_hub_task_id: "f106ac45-c90b-5115-a0de-e986839b19f9"
-```
-
-Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`.
-Replace generated placeholders with repo-specific facts where needed.
-
-## Verify Local Developer Workflow
-
-```task
-id: FLUID-WP-0001-T02
-status: todo
-priority: high
-state_hub_task_id: "1e3f26fe-4a1a-5f96-8dd6-962dd844402e"
-```
-
-Identify the repo's install, test, lint, build, and run commands. Add or refine
-those commands in the agent instructions so future coding sessions can verify
-changes confidently.
-
-## Seed First Real Workplan
-
-```task
-id: FLUID-WP-0001-T03
-status: todo
-priority: medium
-state_hub_task_id: "2428db4a-c6ad-547d-acf3-9163ea17ae20"
-```
-
-Create the first implementation workplan for the repository's most important
-next change. After workplan file updates, run the sync locally from this repo
-checkout:
-
-```bash
-statehub fix-consistency
-```
diff --git a/workplans/FT-WP-0001-telegram-identity-and-hall-channel.md b/workplans/FT-WP-0001-telegram-identity-and-hall-channel.md
deleted file mode 100644
index f16baf9..0000000
--- a/workplans/FT-WP-0001-telegram-identity-and-hall-channel.md
+++ /dev/null
@@ -1,201 +0,0 @@
----
-id: FT-WP-0001
-type: workplan
-title: "Establish HelixForge's Telegram identity and publish the Hall of Helix"
-domain: infotech
-repo: fluid-telegram
-status: active
-owner: worsch
-topic_slug: fluid-telegram
-created: "2026-09-04"
-updated: "2026-09-04"
-planning_priority: high
-planning_order: 1
-depends_on:
-  - FLUID-WP-0008
-related_repos:
-  - fluid-core
-  - helix-forge
-  - hall-of-helix
-state_hub_workstream_id: "a660ed65-700e-5b54-8d91-a556b73518f0"
----
-
-# FT-WP-0001 — Telegram identity and the Hall of Helix channel
-
-Establish a Telegram identity for HelixForge and a channel publishing
-hall-of-helix entries, as the first real FLUID interface.
-
-Everything that could be prepared without credentials has been: the governing
-intent, the R-1 contract, the adapter's connector contract, the observation
-configuration, the seed pressure record, and two competing hypotheses for the
-first experiment. See `docs/` and the handover package at
-`fluid-core/docs/handover/fluid-telegram.md`.
-
-What remains needs either a person with a Telegram account or a running
-adapter.
-
-## T01 — Register the bot
-
-```task
-id: FT-WP-0001-T01
-status: todo
-priority: high
-state_hub_task_id: "a5449e86-3181-54b6-a0fe-e5c761b3e4ba"
-```
-
-**Human step.** Register the HelixForge bot through BotFather (Canon BOT-01).
-Bots are first-class Telegram accounts and need no phone number.
-
-Set the bot's name, description and profile image to something a reader
-encountering it cold would recognise as HelixForge.
-
-Write the token to OpenBao immediately; do not paste it anywhere else, not even
-briefly. Consistent with `HF-WP-0002` (bao.coulomb.social).
-
-## T02 — Create the channels
-
-```task
-id: FT-WP-0001-T02
-status: todo
-priority: high
-state_hub_task_id: "597ab1b7-5903-5a5d-a510-0a6946325404"
-```
-
-**Human step.** Create the **private test channel first**, then the public
-channel (Canon PUB-01). Add the bot as administrator with **Post Messages**
-only — the intent forbids it from using any wider right, so granting one would
-be a permission the system is not allowed to exercise.
-
-Every verification below runs against the private channel. Nothing reaches the
-public channel until the rendering has been seen by a person.
-
-## T03 — Generate and store the redaction salt
-
-```task
-id: FT-WP-0001-T03
-status: todo
-priority: high
-state_hub_task_id: "bbe5da73-e604-5dfe-b25f-fba802f67618"
-```
-
-`openssl rand -hex 32`, stored in OpenBao beside the token, injected as
-`FLUID_REDACTION_SALT`. It must never change: see `docs/observation.md` for why
-rotating it silently invalidates every longitudinal comparison.
-
-## T04 — Record the intent and publish R-1
-
-```task
-id: FT-WP-0001-T04
-status: todo
-priority: high
-state_hub_task_id: "13a92a96-2f87-5de2-a69c-7edc21f3a0c7"
-```
-
-```bash
-export FLUID_INTERFACE=helix-forge-telegram-publishing
-fluid intent put --version IEI-1 --file InterfaceEvolutionIntent.md --activate
-# fill the digest in revisions/R-1.yaml, then
-fluid revision publish --file revisions/R-1.yaml --key-file "$FLUID_SIGNING_KEY" \
-  --adaptation-classes presentation --approved-by "$USER" --traffic-share 1.0
-```
-
-Generate a real signing key pair for this; `--ephemeral-key` is development
-only, and a revision signed with one stops verifying after a restart.
-
-## T05 — Build the adapter
-
-```task
-id: FT-WP-0001-T05
-status: todo
-priority: high
-state_hub_task_id: "c89782da-9896-5957-b729-7c35165a0067"
-```
-
-Implement the three operations in `contracts/r1.openapi.yaml` against the
-connector contract in `docs/adapter-contract.md`. TypeScript with grammY is the
-natural choice; the wire contract makes the language irrelevant to fluid-core.
-
-The two requirements that carry the most weight: publication is idempotent on
-`entry_id`, and an entry that cannot be converted faithfully is refused rather
-than approximated. `entry_content_loss` is a hard guardrail in both competing
-hypotheses and can only be honest if the adapter refuses.
-
-## T06 — Publish one entry to the private channel
-
-```task
-id: FT-WP-0001-T06
-status: todo
-priority: high
-state_hub_task_id: "317bef32-e82e-586a-8947-8cbb330f6c98"
-```
-
-The first real test. Publish a single hall entry to the private channel and
-confirm, by looking at it:
-
-- the rendering is faithful and readable;
-- re-publishing the same entry edits rather than duplicates;
-- the evidence store contains no Telegram user identity and no bot token;
-- `fluid audit trace R-1` reconstructs the publication.
-
-## T07 — Implement both presentation forms as R-2 and R-3
-
-```task
-id: FT-WP-0001-T07
-status: todo
-priority: medium
-state_hub_task_id: "6a91ea08-8814-58f3-8297-a7ca63405294"
-```
-
-R-2 implements `H-tg-teaser`, R-3 implements `H-tg-serial`. Both are
-presentation adaptations over the same contract, so neither needs a contract
-change. Verify both against the private channel before either sees a subscriber.
-
-## T08 — Open the public channel and publish the backlog
-
-```task
-id: FT-WP-0001-T08
-status: todo
-priority: medium
-state_hub_task_id: "5e5cd89a-e7b1-5aaf-9331-ece424afe5e3"
-```
-
-Point the production adapter at the public channel and publish the existing
-entries. 94 entries at once would be both a rate-limit problem and an unkind
-introduction for a new subscriber; publish them oldest-first at a human pace.
-
-Whichever of R-2 or R-3 is used here becomes the de facto control for the
-experiment, which is why `E-tg-length` names R-2 as control rather than R-1.
-
-## T09 — Run the first experiment
-
-```task
-id: FT-WP-0001-T09
-status: todo
-priority: low
-state_hub_task_id: "649e7df6-6c07-5cc8-a022-d1eadcdb7236"
-```
-
-Start `E-tg-length` once the channel has roughly 100 subscribers. Before then
-the evaluator will report INCONCLUSIVE, and that is the correct answer rather
-than a reason to shorten the window.
-
-At one entry per week, a 90-day experiment yields about twelve entries. That is
-thin, and the honest expectation is that the first run is inconclusive and
-informs a better-powered second one. Record that expectation in the experiment's
-amendments rather than discovering it as a disappointment.
-
-## T10 — Close the loop
-
-```task
-id: FT-WP-0001-T10
-status: todo
-priority: low
-state_hub_task_id: "b469b9b8-a1a8-5f76-a1bb-dd51dd4d2ce5"
-```
-
-Record the hypothesis outcome, resolve the competition group, and promote the
-winner. Then confirm `fluid audit trace` reconstructs the whole chain from the
-length-limit pressure through to the promoted revision.
-
-That trace is the deliverable. It is what makes this the first FLUID interface
-rather than a bot that posts to a channel.