kimi-bridge 0.1.0__tar.gz

kimi_bridge-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  tests:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - run: uv sync --locked --all-extras --dev
+      - run: uv run --locked pytest -q
+
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: "3.13"
+          enable-cache: true
+      - run: uv lock --check
+      - run: uv sync --locked --all-extras --dev
+      - run: uv run --locked ruff check .
+      - run: git diff --check
+      - run: uv run --locked python scripts/check_docs.py
+      - run: uv run --locked python scripts/check_kimi_compatibility.py contract --output /tmp/kimi-contract.json
+
+  distribution:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: "3.13"
+          enable-cache: true
+      - run: uv sync --locked --all-extras --dev
+      - run: uv build --no-sources
+      - run: uv run --locked twine check dist/*
+      - run: uv run --locked python scripts/check_distribution.py --dist-dir dist
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 14

kimi_bridge-0.1.0/.github/workflows/kimi-drift.yml

@@ -0,0 +1,63 @@
+name: Kimi compatibility
+
+on:
+  schedule:
+    - cron: "17 19 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: kimi-code-compatibility
+  cancel-in-progress: false
+
+jobs:
+  canary:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: "3.13"
+          enable-cache: true
+      - run: uv sync --locked --dev
+      - name: Run isolated credential-free canary
+        id: canary
+        continue-on-error: true
+        run: uv run --locked python scripts/check_kimi_compatibility.py check --report "$RUNNER_TEMP/kimi-compatibility/report.json" --artifacts "$RUNNER_TEMP/kimi-compatibility/artifacts"
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        if: always()
+        with:
+          name: kimi-compatibility-report
+          path: ${{ runner.temp }}/kimi-compatibility/
+          if-no-files-found: error
+          retention-days: 14
+
+  synchronize:
+    needs: canary
+    if: always() && needs.canary.result == 'success'
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write
+      contents: write
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: "3.13"
+          enable-cache: true
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: kimi-compatibility-report
+          path: ${{ runner.temp }}/kimi-compatibility
+      - run: uv sync --locked --dev
+      - name: Synchronize promotion or rolling drift issue
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          GITHUB_DEFAULT_BRANCH: main
+          GITHUB_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: uv run --locked python scripts/check_kimi_compatibility.py sync --report "$RUNNER_TEMP/kimi-compatibility/report.json"

kimi_bridge-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,87 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          ref: ${{ github.event.release.tag_name }}
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: "3.13"
+          enable-cache: true
+      - run: uv sync --locked --all-extras --dev
+      - name: Verify release identity
+        run: uv run --locked python scripts/check_release.py --tag "$GITHUB_REF_NAME" --commit "$GITHUB_SHA"
+      - run: uv run --locked pytest -q
+      - run: uv run --locked ruff check .
+      - run: git diff --check
+      - run: uv run --locked python scripts/check_docs.py
+      - run: uv build --no-sources
+      - run: uv run --locked twine check dist/*
+      - run: uv run --locked python scripts/check_distribution.py --dist-dir dist
+      - name: Record artifact hashes
+        run: sha256sum dist/* > SHA256SUMS
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: release-${{ github.event.release.tag_name }}
+          path: |
+            dist/
+            SHA256SUMS
+          if-no-files-found: error
+          retention-days: 14
+
+  release-assets:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: release-${{ github.event.release.tag_name }}
+          path: release-bundle
+      - name: Verify artifact hashes
+        working-directory: release-bundle
+        run: sha256sum --check SHA256SUMS
+      - name: Attach distributions and hashes
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release upload "$GITHUB_REF_NAME" release-bundle/dist/* release-bundle/SHA256SUMS --clobber --repo "$GITHUB_REPOSITORY"
+
+  pypi-publish:
+    needs: [build, release-assets]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/kimi-bridge
+    permissions:
+      actions: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: release-${{ github.event.release.tag_name }}
+          path: release-bundle
+      - name: Verify artifact hashes
+        working-directory: release-bundle
+        run: sha256sum --check SHA256SUMS
+      - uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1
+        with:
+          packages-dir: release-bundle/dist/
+          verify-metadata: true
+          attestations: true

kimi_bridge-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+.ruff_cache/
+roadmap/
+.env

kimi_bridge-0.1.0/AGENTS.md

@@ -0,0 +1,37 @@
+# AGENTS.md
+
+Guidance for AI agents (and humans) working in this repo.
+
+## Project state
+
+**The managed server client, Feishu bridge, and experimental Telegram adapter are implemented, including interactive approvals/questions, prompt steering, inbound media, semantic outbound files, separately streamed optional thinking, compatibility diagnostics, and credential-free contract monitoring.** Feishu is live-validated; Telegram is fake-tested but not live-validated. The core contracts are platform-neutral, and the runtime intentionally enables one selected adapter per process. Public behavior and architectural requirements live in `docs/ARCHITECTURE.md`, `docs/CONFIGURATION.md`, and `docs/COMMANDS.md`; changing those contracts requires explicit user sign-off and matching documentation in the same change.
+
+## Layout
+
+- `src/kimi_bridge/kimi_server/` — the ONLY package that talks to kimi-code. Its facade, client, supervisor, types, wire/event helpers, probe, and semantic-contract modules form one boundary; platform adapters, automation, and the router must stay free of kimi-server API details.
+- `src/kimi_bridge/interactions.py` — platform-neutral approval/question prompts, answers, responses, and outcomes.
+- `src/kimi_bridge/router/` — the platform-neutral routing package. `core.py` exposes the single `ChatRouter` facade; command orchestration, session/stream lifecycle, interaction lifecycle, answer/thinking rendering, file authorization, formatting, and private runtime state stay in their focused modules. The package must not construct platform UI payloads or choose native media types.
+- `src/kimi_bridge/platforms/` — one adapter per IM platform, behind the semantic `PlatformAdapter` protocol in `base.py`. Native text/file rendering, uploads, and callback decoding stay inside the platform package.
+- `src/kimi_bridge/platforms/feishu.py` and `feishu_cards.py` — Feishu Markdown posts, native media uploads/messages, card JSON, and callback decoding. Bundled native-rendering assets live below `src/kimi_bridge/assets/` and must be loaded with package resources so wheel installs work.
+- `src/kimi_bridge/platforms/telegram.py` — the handwritten Telegram Bot API transport and adapter. Telegram update dictionaries, multipart uploads, inline keyboards, callback tokens, `ForceReply` wizard state, retry policy, and file downloads stay here.
+- `src/kimi_bridge/state.py` — versioned bridge-owned conversation state. New schema changes require an explicit migration that preserves existing bindings; unknown future versions must still fail loudly.
+- `scripts/check_kimi_compatibility.py` and `.github/workflows/kimi-drift.yml` — credential-free semantic contract checking and quiet supported-version promotion. Protocol knowledge must remain in `kimi_server`; automation consumes its projection.
+
+## kimi server API
+
+- Tested runtime versions are the immutable `src/kimi_bridge/supported-kimi-code-versions.json` manifest loaded by `compatibility.py`. Unknown official Kimi Code versions warn and attempt the live contract; executable/server version mismatches and legacy Python `kimi-cli` fail. Start the server with `kimi web --no-open --host 127.0.0.1 --port <p>`; it stays in the foreground and prints the bearer token at startup.
+- Specs are served at runtime: `GET /openapi.json` (REST) and `GET /asyncapi.json` (WebSocket). Consult them instead of guessing field names; note the API is 0.x and may shift between kimi-code releases — check `server_version` in `/api/v1/meta`.
+- Stored sessions must be materialized through `GET /api/v1/sessions/{session_id}/status` before each initial or reconnected WebSocket subscription. This lifecycle detail belongs only in the `kimi_server` package.
+- Auth: `Authorization: Bearer <token>` header on REST and WS.
+
+## Conventions
+
+- Python ≥ 3.11, asyncio throughout, typed (dataclasses / Protocol, `from __future__ import annotations`).
+- Minimal dependencies: core is `httpx` + `websockets` only. Feishu uses the optional `lark-oapi` SDK; Telegram reuses `httpx` and must not gain a framework dependency without an explicit design change.
+- Keep the shared contracts semantic and platform-neutral. Do not introduce a generic UI schema, plugin framework, capability registry, or multi-adapter runtime without a concrete second platform requiring it.
+- Keep public documentation compact and current. Do not expose private credentials, local planning material, ignored reference snapshots, or internal progress terminology in package metadata, docs, workflows, issues, or releases.
+- If a file is gitignored, it's gitignored for a reason — never force-add it.
+
+## Testing
+
+Unit-test the router against a fake `KimiServerClient` and fake adapters. Router tests assert semantic interactions, path authorization, state migration, and independent stream behavior; platform tests assert native rendering, uploads, and callback decoding. Keep server supervision, REST/WebSocket recovery, Feishu filtering, Telegram Bot API transport, configuration, and state persistence behind fakes in CI; do not require a live Kimi server or real IM credentials. The standalone smoke script is the explicit authenticated live-server check. Distribution changes also require building source and wheel artifacts, checking metadata/license/bundled assets, and exercising isolated core and Feishu-extra `uv tool` installs through non-starting `--help`, `--version`, and `doctor` before uninstalling them.

kimi_bridge-0.1.0/INSTALL.md

@@ -0,0 +1,177 @@
+# Install and operate kimi-bridge
+
+This is the starting runbook for both humans and coding agents. An agent should inspect the machine first, explain what it found, and pause at every user decision or credential boundary. Do not claim success until the selected chat adapter has been exercised by its allowlisted user.
+
+## 1. Inspect before changing anything
+
+Confirm that the host is Linux and inventory existing tools without installing or replacing them:
+
+```bash
+uname -s
+python3 --version
+command -v uv || true
+command -v kimi || true
+kimi --version
+kimi --help
+kimi doctor config
+```
+
+kimi-bridge requires Linux, Python 3.11 or newer, [uv](https://docs.astral.sh/uv/getting-started/installation/), and authenticated official [Kimi Code](https://moonshotai.github.io/kimi-code/en/guides/getting-started). Official Kimi Code has `web`, `doctor`, and `migrate` commands. The older Python product prints a `kimi, version ...` banner and is incompatible; do not install or retain legacy `kimi-cli` as a workaround. Follow Moonshot AI's current installation or migration guide when Kimi Code is absent or legacy.
+
+Ask the user which adapter they want before configuring anything:
+
+- Feishu requires an app ID, app secret, and at least one Feishu `open_id` or `user_id`.
+- Experimental Telegram requires a bot token and at least one stable numeric Telegram user ID. Usernames are not authorization identities.
+
+Do not ask the user to paste credentials into a repository file. Do not print, log, commit, or echo credentials or real allowlist values. If a secret already exists in a protected environment file or secret manager, transfer it locally without displaying it. Otherwise ask the user to enter it through a private local editor or another secret-safe channel. Avoid commands that leave secrets in shell history.
+
+## 2. Install from PyPI
+
+For Feishu, install the optional SDK extra:
+
+```bash
+uv tool install 'kimi-bridge[feishu]'
+```
+
+For the experimental Telegram adapter, the core package is sufficient:
+
+```bash
+uv tool install kimi-bridge
+```
+
+Check the exposed command:
+
+```bash
+command -v kimi-bridge
+kimi-bridge --version
+kimi-bridge --help
+```
+
+If `uv` reports that its tool bin directory is not on `PATH`, run `uv tool update-shell`, then start a fresh shell. Do not replace a working installation merely because its resolved path differs from an example in this guide.
+
+## 3. Create protected configuration
+
+Create the private configuration directory, then let the user populate the selected adapter's values using the [configuration reference](docs/CONFIGURATION.md):
+
+```bash
+install -d -m 700 ~/.kimi-bridge
+touch ~/.kimi-bridge/config.toml
+chmod 600 ~/.kimi-bridge/config.toml
+```
+
+Do not place secrets in environment files inside the project. After the file is populated, inspect only its ownership, mode, and redacted structure. Never include its contents in tool output or a diagnostic report.
+
+Run the non-starting diagnostic:
+
+```bash
+kimi-bridge doctor
+```
+
+`doctor` loads configuration, checks secret-file permissions and writable paths, fingerprints the `kimi` executable, classifies its version, and runs Kimi's non-starting configuration check. It reports only credential presence and allowlist counts. Warnings return success; blocking errors return nonzero. Resolve every error before continuing and explain any warning rather than suppressing it.
+
+## 4. Verify in the foreground
+
+Start the bridge from a normal shell:
+
+```bash
+kimi-bridge
+```
+
+Ask the allowlisted user to send `/status`, then send one small prompt and confirm that its reply streams and completes without a duplicate message. Exercise an approval or question if the selected permission mode requires it. Stop with `Ctrl-C` and confirm clean shutdown.
+
+For Feishu, do not call the setup complete until direct messages, editable replies, and any configured card callbacks work. For Telegram, state plainly that its adapter remains experimental and was not live-validated by the project unless this installation's own private-chat test actually passed.
+
+## 5. Optional per-user systemd service
+
+Do not create a service automatically. First ask: “Do you want kimi-bridge to run persistently as your user?” A foreground-only installation is complete if the answer is no.
+
+If the user says yes, resolve the actual executable locations before creating anything:
+
+```bash
+command -v kimi-bridge
+command -v kimi
+uv tool dir --bin
+```
+
+The repository includes [a user-unit template](docs/kimi-bridge.service). Its default paths match uv's usual user tool directory and Kimi Code's usual installer directory, but an agent must replace `ExecStart` and the `PATH` entries when the commands above report different absolute paths. Do not put credentials in the unit.
+
+After receiving approval to create the service, place the reviewed unit at `~/.config/systemd/user/kimi-bridge.service`, then validate and reload it without starting it:
+
+```bash
+install -d -m 700 ~/.config/systemd/user
+install -m 600 docs/kimi-bridge.service ~/.config/systemd/user/kimi-bridge.service
+systemd-analyze --user verify ~/.config/systemd/user/kimi-bridge.service
+systemctl --user daemon-reload
+```
+
+The copy command assumes a source checkout. For a PyPI-only installation, create the same reviewed unit from the linked template. If `systemd-analyze --user` is unavailable, report that syntax validation remains pending rather than skipping it silently.
+
+Pause again and ask for explicit approval before enabling or starting the unit. Only after approval:
+
+```bash
+systemctl --user enable --now kimi-bridge.service
+systemctl --user status kimi-bridge.service
+journalctl --user -u kimi-bridge.service --since today
+```
+
+Review the journal for startup success and confirm it contains no credential values. Repeat the same `/status` and streamed-reply chat check against the service.
+
+By default, a user service follows the user's login session. `loginctl enable-linger "$USER"` makes the user manager start at boot and remain available after logout. Treat lingering as a separate user decision because it changes host lifecycle behavior; never enable it silently. Disabling it later uses `loginctl disable-linger "$USER"`.
+
+## Operations
+
+Inspect and follow logs:
+
+```bash
+systemctl --user status kimi-bridge.service
+journalctl --user -u kimi-bridge.service -f
+```
+
+Restart after an approved configuration change:
+
+```bash
+kimi-bridge doctor
+systemctl --user restart kimi-bridge.service
+```
+
+Upgrade, validate, and restart:
+
+```bash
+uv tool upgrade kimi-bridge
+kimi-bridge --version
+kimi-bridge doctor
+systemctl --user restart kimi-bridge.service
+```
+
+Pin a known release for rollback, retaining the Feishu extra when applicable:
+
+```bash
+uv tool install --force 'kimi-bridge[feishu]==0.1.0'
+```
+
+Use `kimi-bridge==0.1.0` instead for the core installation, then rerun `doctor` and restart the service.
+
+Stop and disable the service without deleting user data:
+
+```bash
+systemctl --user disable --now kimi-bridge.service
+```
+
+After the user confirms removal, delete only `~/.config/systemd/user/kimi-bridge.service`, run `systemctl --user daemon-reload`, and uninstall the tool:
+
+```bash
+uv tool uninstall kimi-bridge
+```
+
+Uninstalling the tool or service must preserve `~/.kimi-bridge/config.toml`, `state.json`, workspaces, inbound files, and Kimi sessions unless the user separately asks to remove those specific paths.
+
+## Install from a checkout
+
+Contributors can use an isolated tool directly from a trusted checkout:
+
+```bash
+uv tool install .
+uv tool install --force '.[feishu]'
+```
+
+For development and validation commands, see [README](README.md#development).

kimi_bridge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mtrya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kimi_bridge-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: kimi-bridge
+Version: 0.1.0
+Summary: Control a local Kimi Code agent from Feishu or Telegram
+Project-URL: Homepage, https://github.com/Mtrya/kimi-bridge
+Project-URL: Repository, https://github.com/Mtrya/kimi-bridge
+Project-URL: Issues, https://github.com/Mtrya/kimi-bridge/issues
+Project-URL: Documentation, https://github.com/Mtrya/kimi-bridge#readme
+Project-URL: Changelog, https://github.com/Mtrya/kimi-bridge/releases
+Author: Mtrya
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,chatbot,feishu,kimi-code,telegram
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.11
+Requires-Dist: httpx
+Requires-Dist: websockets
+Provides-Extra: feishu
+Requires-Dist: lark-oapi<2,>=1.7.1; extra == 'feishu'
+Description-Content-Type: text/markdown
+
+# kimi-bridge
+
+Control a local [Kimi Code](https://github.com/MoonshotAI/kimi-code) agent from an instant-messaging conversation.
+
+kimi-bridge supervises Kimi Code's local server, keeps chat-to-session bindings across restarts, streams editable replies, and brings approvals, questions, steering, files, thinking output, and session controls into your chat client.
+
+## Support
+
+| Surface | Status | Validation |
+| --- | --- | --- |
+| Feishu direct messages | Supported | Live-validated end to end |
+| Telegram private chats | Experimental | Fake Bot API tests only; not live-validated |
+| Linux, Python ≥3.11 | Supported | Hosted tests on 3.11 and 3.13 |
+| macOS and Windows | Not currently supported | — |
+
+Only one adapter runs in each bridge process. Feishu uses the official `lark-oapi` WebSocket client. Telegram uses a small handwritten `httpx` Bot API transport without a Telegram framework.
+
+## Features
+
+- Durable Kimi session creation, listing, switching, renaming, inspection, compaction, and undo.
+- Edit-in-place answer streaming, router-side chunking, and optional separate thinking output.
+- Interactive approvals and questions with timeout handling and stale-action protection.
+- Busy-turn prompt steering, cancellation, permission modes, model/effort/plan controls, goals, tasks, skills, and read-only MCP inspection.
+- Inbound images and files plus workspace-contained outbound `/send`.
+- Private-chat allowlists, loopback-only Kimi server supervision, and a secret-safe non-starting doctor command.
+
+## Quick start
+
+Install and authenticate official [Kimi Code](https://moonshotai.github.io/kimi-code/en/guides/getting-started), then install [uv](https://docs.astral.sh/uv/getting-started/installation/) and kimi-bridge.
+
+For Feishu:
+
+```bash
+uv tool install 'kimi-bridge[feishu]'
+```
+
+For the experimental Telegram adapter:
+
+```bash
+uv tool install kimi-bridge
+```
+
+Create `~/.kimi-bridge/config.toml` for one adapter, protect it with `chmod 600`, and validate the installation without starting the server or connecting to chat:
+
+```bash
+kimi-bridge doctor
+```
+
+Then run:
+
+```bash
+kimi-bridge
+```
+
+Start with the [installation runbook](INSTALL.md), especially when asking a coding agent to configure the bridge. The [configuration reference](docs/CONFIGURATION.md) contains complete Feishu and Telegram examples.
+
+## Commands
+
+Commands cover:
+
+- sessions: `/new`, `/sessions`, `/switch`, `/status`, `/title`, `/usage`, `/compact`, `/undo`;
+- control: `/mode`, `/model`, `/effort`, `/plan`, `/goal`, `/stop`;
+- tasks and tools: `/tasks`, `/skills`, `/mcp`;
+- output: `/send`, `/render-thinking`.
+
+Use `/help` in chat or read the [command reference](docs/COMMANDS.md) for exact grammar, busy-session behavior, and platform media semantics.
+
+## Architecture and security
+
+```text
+Feishu or experimental Telegram
+              │
+              ▼
+       semantic chat router
+              │
+              ▼
+  supervised local `kimi web`
+```
+
+The Kimi client owns all REST, WebSocket, version, and process-lifecycle details. The router owns platform-neutral session and interaction behavior. Each adapter owns its native transport and UI payloads. See [Architecture](docs/ARCHITECTURE.md) for the full boundary.
+
+The managed Kimi server binds to loopback and uses its generated bearer token. Chat access is restricted by the selected adapter's allowlist, but kimi-bridge is designed for one trusted operator, not mutually untrusted tenants. A permitted Kimi agent can read, write, and execute within the authority of the host account, so protect both the host and chat credentials.
+
+Tested Kimi Code versions are recorded in a packaged compatibility manifest. An unlisted official version emits a loud warning and is attempted against the live contract; legacy Python `kimi-cli`, an unrecognized product, or an executable/server version mismatch fails. Run `kimi-bridge doctor` after every Kimi or bridge upgrade.
+
+## Documentation
+
+- [Install and operate](INSTALL.md)
+- [Configure](docs/CONFIGURATION.md)
+- [Commands and interactions](docs/COMMANDS.md)
+- [Architecture and compatibility](docs/ARCHITECTURE.md)
+- [Upstream Kimi Code](https://moonshotai.github.io/kimi-code/en/guides/getting-started)
+- [Report an issue](https://github.com/Mtrya/kimi-bridge/issues)
+
+## Development
+
+```bash
+uv sync --all-extras --dev
+uv run pytest -q
+uv run ruff check .
+uv run python scripts/check_docs.py
+uv run python scripts/smoke_server.py
+```
+
+Unit tests use fake Kimi, Feishu, Telegram, WebSocket, state, and process boundaries. The smoke script is the explicit authenticated local-server check; hosted checks use no credentials or inference.
+
+## License
+
+[MIT](LICENSE) © 2026 Mtrya