From be285394662732c2d614021e3bf078e6fa53b2fe Mon Sep 17 00:00:00 2001 From: lagrangee Date: Fri, 2 Oct 2026 14:36:21 +0800 Subject: [PATCH] docs: position Bearing alongside Matt and Wayfinder --- README.md | 209 +++++++++------------ README.zh-CN.md | 214 ++++++++++------------ tests/agent-installation-contract.test.ts | 12 +- tests/demo-pages-contract.test.ts | 10 +- 4 files changed, 200 insertions(+), 245 deletions(-) diff --git a/README.md b/README.md index 92152156..7dae137f 100644 --- a/README.md +++ b/README.md @@ -1,183 +1,152 @@ # Bearing -## Stay on the same page with your coding agents. + -Bearing gives long-running coding-agent projects a local, inspectable project-governance layer. It keeps accepted direction, Planning Reviews, evidence, and current Audit findings visible to you and your agents, so new work can start from the same project picture instead of from a fragile memory of old chats. +## Let Wayfinder chart the work. Keep the project in view. -Local-first · Open-source Public Preview · Agent-mediated installation · Matt-native local Markdown work management +Bearing adds local-first project governance to [Matt Pocock's skills](https://github.com/mattpocock/skills). It connects Wayfinder Maps and delivery work to the project's direction, milestones, and decision evidence. -[Quickstart](#quickstart-complete-one-real-alignment-loop) · [Is Bearing for you?](#is-bearing-for-you) · [Data boundary](#local-first-data-and-trust-boundary) · [中文 README](README.zh-CN.md) +Keep using the workflow you know. Bearing helps you and your coding agent see why each piece of work matters, how it relates to the rest, and what still needs a decision. -## The aha moment - -You ask an agent to do the next thing on an active project: - -> Add team accounts next. - -A Bearing-aware agent can answer from the current project truth: - -> The focused Gate is proving the single-user workflow. The accepted Roadmap puts multi-user authentication later. We can keep the current direction and capture this as future work, revise the Roadmap, or split a separate outcome horizon. I will not treat this as aligned until you choose. - -That is the point of Bearing: not perfect agent memory, and not a second task tracker, but continuous alignment confidence. You can feel that the agent is on the same page, and you can see the source of that shared picture. - -## What Bearing connects - -```text -You + your coding agent - ↕ - Bearing Project Governance - ↕ -Matt-native Maps and Tickets - -Portal reads the same project picture -``` - -Bearing owns durable project governance: Project Summary, Roadmaps, Milestone Gates, Effort bindings, Authorities, Assets, Planning Reviews, Planning Audit, and evidence relationships. - -Your work-management adapter still owns Maps, Tickets, dependencies, claims, blockers, and resolution. Your executor still owns implementation and verification. Bearing keeps those layers connected without pretending to be all of them. +Open-source Public Preview · macOS · Local Markdown · MIT -Already using Matt Pocock's planning workflow? Bearing is designed to read the same local Markdown Map and Ticket shape, so you can add governance and Portal orientation without migrating work into another tracker. +[Try the Portal demo](https://lagrangee.github.io/bearing/) · [Get started](#quickstart-complete-one-real-alignment-loop) · [中文 README](README.zh-CN.md) -## Is Bearing for you? +## The aha moment -Bearing is likely a fit if: +You have a Wayfinder Map for onboarding, another for billing, and a third for performance. Each has a destination and a record of decisions. Now you need to answer a project-level question: -- you use coding agents on software projects that continue across many sessions; -- you want new requests checked against accepted direction before work starts; -- you already use, or are willing to use, the supported Matt-native local Markdown Map and Ticket workflow; -- you want local repository truth, a local Portal, and no automatic telemetry; -- you are comfortable with a macOS-first `0.x` Public Preview that may make documented breaking changes. +> Which of these efforts brings us closer to the next milestone? Does adding team accounts still fit the direction we agreed on? -Bearing is probably not a fit yet if: +Bearing connects the work you select to an accepted Roadmap and Milestone Gates. You and your agent can trace a Map back to the commitment it serves, inspect the evidence, and decide whether to continue, change direction, or take on a separate goal. -- your work is mostly one-off coding tasks with little durable context; -- you want a Kanban board, hosted issue tracker, autonomous project manager, or general memory database; -- you do not want to use the supported local Markdown work-management adapter; -- you need hosted multi-user operation, product-managed authentication, cloud sync, or a public Internet Portal; -- you need officially supported Linux or Windows today. +Wayfinder preserves the route through an effort. Bearing keeps that effort connected to the whole project. -## Public Preview support +## What Bearing connects -| Area | Public Preview support | +| When you need to… | Bearing helps you… | | --- | --- | -| Platform | macOS | -| Node.js | Node.js 24.15.0 or later; CI verifies Node.js 24.15.0 and 26 | -| Work Management Adapter | Matt-native local Markdown Maps and Tickets | -| Telemetry | None. Bearing performs no analytics, crash upload, repository upload, or update polling. | +| Understand how several Maps fit together | Follow each selected effort back to its project direction and milestone. | +| Decide whether a new request fits | Inspect relevant planning and work, then surface conflicts and decision paths. | +| Review progress | Connect Efforts, native Maps and Tickets, evidence, and human acceptance without treating them as the same status. | +| Understand what your agent is using | Read the project's planning lineage, source provenance, and attention items in the local Portal. | -## Interactive browser sample +A typical Wayfinder-based project looks like this: + +```text +Roadmap — the project direction + └─ Milestone Gate — the outcome to prove + ├─ Effort — one accepted commitment + │ └─ Wayfinder Map and related native work + └─ Effort — another accepted commitment + └─ Wayfinder Map and related native work +``` -[Open the interactive browser sample](https://lagrangee.github.io/bearing/). It is a browser-only -Portal demo with fixed mock Northstar data. The demo is a static sample, not a hosted Bearing -project, real repository, canonical planning surface, or proof of product value. It does not start -the local Portal Host, read a repository, call a provider or API, use analytics, or persist browser -state. +An **Effort** is Bearing's unit for one accepted work commitment. When you bring a Wayfinder effort into Bearing, the Map's native work scope connects to that Effort. The Map continues to organize exploration and decisions; the Effort records why the work exists and which project milestone it serves. -Supported product use starts with [local installation](#quickstart-complete-one-real-alignment-loop) -and a loopback Portal. Demo availability does not prove installation success. Read the -[data and security boundary](docs/data-and-security.md) before sharing Portal captures or changing -private reachability. The demo remains independent from production Portal runtime and is excluded -from the npm package. +A resolved Map can lead into specification and delivery while the Effort continues. Ticket completion and acceptance remain visible as separate facts. You choose which work to include; planned Efforts and direct delivery work can also exist without a Map. -## Feedback and support +### Alongside Matt's workflow -- Use [Bug report](https://github.com/lagrangee/bearing/issues/new?template=bug_report.yml) or [Documentation problem](https://github.com/lagrangee/bearing/issues/new?template=documentation.yml) for reproducible bugs and actionable documentation problems. Blank Issues are disabled. -- Use [Q&A](https://github.com/lagrangee/bearing/discussions/categories/q-a) for questions and troubleshooting, and [Ideas](https://github.com/lagrangee/bearing/discussions/categories/ideas) for experiences, scenarios, pain points, suggestions, and feature ideas that still need shaping. -- Report suspected vulnerabilities only through [GitHub private vulnerability reporting](https://github.com/lagrangee/bearing/security/advisories/new), never in a public Issue or Discussion. +- **Wayfinder** works through the unknowns and retains decisions in a Map. +- **Specification and ticket skills** turn accepted decisions into delivery work when needed. +- **Your executor** implements and verifies that work. +- **Bearing** connects these activities to project direction, milestones, and evidence. Its local Portal lets you inspect the same picture your agent uses. -Issues and Discussions are public GitHub data. Do not submit tokens, secrets, private source, complete planning state, real absolute repository paths, or unredacted screenshots. Bearing uploads no diagnostics automatically; logs, diagnostics, and repository excerpts are shared only when you explicitly submit them. Community support is best-effort with no SLA, and public feedback is not a scheduling or delivery commitment. +The supported Public Preview path reads Matt-native local Markdown Maps, Specs, and Tickets. Your tracker keeps its native files, status, dependencies, claims, and resolution rules. Bearing's Portal is read-oriented; canonical planning decisions stay in the agent conversation. ## Quickstart: complete one real alignment loop -### 1. Ask your Agent to install Bearing +You need macOS, Node.js 24.15.0 or later, a coding agent that can install packages and integrate a skill, and a real Git project. The supported work-management path uses Matt-native local Markdown Maps and Tickets. -Give your Agent this prompt. It can follow the separate -[Agent installation guide](docs/agent-installation.md) without adding implementation detail to this -README. +### 1. Ask your agent to install Bearing ```text Install Bearing from https://github.com/lagrangee/bearing. Follow the repository's Agent installation guide, use the released package, integrate the Bearing skill with your Skill Directory, and stop before repository setup. ``` -#### Terminal fallback +The [Agent installation guide](docs/agent-installation.md) verifies one exact published package and separates installation, skill integration, and repository setup. It does not install from mutable `main` as the normal payload. -If your Agent cannot perform the installation, select and verify an exact released version, then -run that candidate's explicit installer: +If your agent cannot install it, first verify an exact released version and its package identity, then use the terminal fallback: ```bash -npx @lagrangee/bearing@ install +npx --yes @lagrangee/bearing@ install ``` -Install stages and validates one complete bundle, then either switches it as a unit or restores the -previous complete bundle. It does not initialize a repository or launch Portal. Bare `bearing` -shows concise help. Explicit `bearing uninstall` removes only the Global Kit, canonical CLI, and -known owned Agent Surface links; it preserves the Project Catalog and every repository. An older -candidate and an unverifiable current Kit are no-write outcomes; see -[Troubleshooting](docs/troubleshooting.md). Successful install prints classic PATH guidance without -writing or sourcing a shell profile. +Installation prints PATH guidance without changing your shell profile. See [Getting started](docs/getting-started.md) and [Troubleshooting](docs/troubleshooting.md) for setup and recovery. -Advanced users and agents can use explicit commands; see [CLI reference](docs/cli.md). +### 2. Enable Bearing in your project -### 2. Choose a real project - -Start with a real Git repository that already has, or is ready to use, the supported local Markdown Map and Ticket workflow. Bearing creates first value when it can connect real direction to real work; an empty toy repository proves very little. - -### 3. Ask your Agent to set up Bearing - -Open the repository with your Agent and ask: +Open the project with your agent and ask: ```text -Set up Bearing for this project. Use the existing Map and Tickets as work context, and guide me through the minimum governance baseline. +Set up Bearing for this project. Help me connect one existing Wayfinder Map and its work to the project's direction and milestones. Show me the proposed scope and planning baseline before applying them. ``` -The minimum useful baseline is: - -- one current Project Summary; -- one active Roadmap and focused Milestone Gate; -- one Effort that binds an existing Map or Ticket scope to that Gate. +Start with a Project Summary, a Roadmap and Milestone Gate, and an Effort connecting the selected work to that Gate. Use a Map you actually work with. Your agent should make proposed direction and scope visible for your decision; repository files alone do not accept a plan. -Accepted direction remains a human decision. Repository Configuration must not infer governance truth from repository files without asking. - -### 4. Bring one real request - -Ask something you actually want to do next: +### 3. Bring one real request ```text Before we start, check this against the current direction, accepted decisions, and active work. Surface any conflict before acting. ``` -The first alignment loop is complete when the agent either explains how the request fits or exposes a material conflict with explicit decision paths. Installation success alone is not the value milestone. +The first useful loop is complete when your agent explains how the request fits or surfaces a material conflict with clear decision paths. -### 5. Inspect the current project +### 4. Inspect the shared picture ```bash bearing inspect project --repo . bearing portal ``` -Open the loopback URL printed by the Portal Host and inspect the Project Summary, focused Roadmap and Gate, contributing Effort, Attention, and source provenance. +Open the loopback URL printed by the Portal Host. Inspect the Project Summary, Roadmaps and Gates, contributing Efforts, Attention, and source provenance. Advanced usage is in the [CLI reference](docs/cli.md). + +## Is Bearing for you? + +Bearing is likely a fit if you already use Matt Pocock's skills, especially Wayfinder, on a software project with several ongoing efforts. It is useful when individual Maps and Tickets are understandable, but their relationship to the project's direction needs to stay visible. + +The `0.x` Preview may make documented breaking changes; Linux and Windows are not officially supported today. + +One-off tasks with little lasting context may get less value. If you need a hosted issue tracker, Kanban board, autonomous project manager, general memory database, multi-user service, or cloud sync, those are outside the current product boundary. + +## Public Preview support + +| Area | Public Preview support | +| --- | --- | +| Platform | macOS | +| Node.js | Node.js 24.15.0 or later; CI verifies Node.js 24.15.0 and 26 | +| Work Management Adapter | Matt-native local Markdown Maps and Tickets | +| Telemetry | None. No analytics, crash upload, repository upload, or update polling. | + +## Interactive browser sample + +[Open the interactive browser sample](https://lagrangee.github.io/bearing/) to explore the Portal with fixed mock Northstar data. + +The demo is a static browser sample. It does not start the local Portal Host, read a repository, call a provider or API, use analytics, or persist browser state. It is excluded from the npm package. Demo availability does not prove installation success or product value; real use starts with local installation and a loopback Portal. ## Local-first data and trust boundary -- Repository governance truth lives under the repository's Bearing state and native local Markdown work scope. -- User-level installation and Project Catalog data live under the user's Bearing home directory. -- `.bearing/cache` is disposable projection data; source truth remains in canonical state and native work files. -- Portal's owner-facing Catalog API and UI show absolute repository roots. Screenshots and user-shared diagnostics may therefore reveal local paths and must be redacted before sharing. -- Direct loopback Portal uses HTTP, so its session cookie is not marked `Secure`; restarting the foreground Portal Host invalidates the session. -- Private Tailscale Serve or an owner-managed reverse proxy may provide private reachability, but the owner is responsible for TLS, authentication, access control, and exposure. Public unauthenticated Internet exposure is unsupported. -- Bearing is a local trusted-checkout tool. It is not a filesystem sandbox and does not claim safety against hostile concurrent filesystem mutation. +- Canonical project governance lives in `.bearing/state/`; native work stays in its selected local Markdown scope. `.bearing/cache` is disposable projection data. +- The Global Kit and Project Catalog live under your local Bearing home directory. +- Bearing performs no analytics, crash upload, repository upload, or update polling. An explicit install or update check accesses the package registry; feedback leaves your machine only when you submit it. +- Portal's owner-facing Catalog shows absolute repository roots. Redact local paths and private data before sharing screenshots or diagnostics. +- Direct loopback Portal uses HTTP; its session cookie is not marked `Secure`, and restarting the foreground Host invalidates the session. +- Private Tailscale Serve or an owner-managed reverse proxy requires you to manage TLS, authentication, access control, and exposure. Public unauthenticated Internet exposure is unsupported. +- Bearing is a trusted-checkout tool. It is not a filesystem sandbox and does not claim safety against hostile concurrent filesystem mutation. + +Read [Data and security](docs/data-and-security.md) and [SECURITY.md](SECURITY.md) before sharing captures or changing private reachability. + +## Feedback and support + +- [Bug report](https://github.com/lagrangee/bearing/issues/new?template=bug_report.yml) and [Documentation problem](https://github.com/lagrangee/bearing/issues/new?template=documentation.yml): reproducible defects and actionable documentation problems. Blank Issues are disabled. +- [Q&A](https://github.com/lagrangee/bearing/discussions/categories/q-a) and [Ideas](https://github.com/lagrangee/bearing/discussions/categories/ideas): troubleshooting, experiences, and proposals that still need shaping. +- [GitHub private vulnerability reporting](https://github.com/lagrangee/bearing/security/advisories/new): suspected vulnerabilities. Never post them in a public Issue or Discussion. -Read more in [Data and security](docs/data-and-security.md) and [SECURITY.md](SECURITY.md). +Issues and Discussions are public GitHub data. Do not submit tokens, secrets, private source, complete planning state, real absolute repository paths, or unredacted screenshots. Share only the smallest redacted excerpt needed. Community support is best-effort with no SLA; public feedback is not a scheduling or delivery commitment. ## Learn, recover, and contribute -- [Getting started](docs/getting-started.md) -- [Everyday workflows](docs/everyday-workflows.md) -- [Data and security](docs/data-and-security.md) -- [Troubleshooting](docs/troubleshooting.md) -- [CLI reference](docs/cli.md) -- [Contributing](CONTRIBUTING.md) -- [Code of Conduct](CODE_OF_CONDUCT.md) -- [Third-party notices](THIRD_PARTY_NOTICES) +[Getting started](docs/getting-started.md) · [Everyday workflows](docs/everyday-workflows.md) · [Troubleshooting](docs/troubleshooting.md) · [CLI reference](docs/cli.md) · [Contributing](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md) · [Third-party notices](THIRD_PARTY_NOTICES) Bearing is open-source under the MIT License. diff --git a/README.zh-CN.md b/README.zh-CN.md index 91f14b45..31d082ca 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,179 +1,165 @@ # Bearing -## 始终与你的 coding agents 保持在同一页上。 + -Bearing 为长期 coding-agent 项目提供一个本地、可检查的项目治理层。它把已经接受的方向、Planning Reviews、证据和 current Audit findings 保持可见，让你和 agent 每次开始新工作时都能回到同一幅项目全貌，而不是依赖旧对话里脆弱的记忆。 +## 用 Wayfinder 想清楚每件事，用 Bearing 看清整个项目。 -Local-first · 开源 Public Preview · Agent 代办安装 · Matt-native 本地 Markdown work management +如果你已经在用 [Matt Pocock 的 skills](https://github.com/mattpocock/skills) 做项目，Bearing 可以把 Wayfinder 的 Map、后续任务和交付依据，连接到项目方向与阶段目标。 -[Quickstart](#quickstart完成一次真实-alignment-loop) · [Bearing 适合你吗？](#bearing-适合你吗) · [数据边界](#local-first-数据与信任边界) · [English README](README.md) +继续沿用熟悉的工作流。你和 agent 都能看清：这件事为什么做，和其他工作有什么关系，现在的进展是否仍符合当初的决定。 -## Aha moment +开源预览版 · 本地运行 · macOS · MIT 协议 -你在一个活跃项目里让 agent 做下一件事： +[先看 Portal 演示](https://lagrangee.github.io/bearing/) · [开始使用](#开始使用) · [English](README.md) -> 接下来加入团队账号。 + -理解 Bearing 的 agent 可以根据当前项目 truth 回答： +## 每份 Map 都很清楚，整个项目呢？ -> 当前 focused Gate 正在证明单用户工作流。已经接受的 Roadmap 把多用户认证放在后续。我们可以保持当前方向并记录为未来工作、修改 Roadmap，或者拆出一个独立 outcome horizon。在你选择之前，我不会把这件事视为已经对齐。 +你用 Wayfinder 理清了新用户引导，又为计费和性能优化各建了一份 Map。每件事都有目标，也留下了讨论和决定。接下来，问题变成了： -这就是 Bearing 的价值：不是完美的 agent 记忆，也不是第二套任务系统，而是持续的 alignment confidence。你能感觉 agent 和你在同一页上，也能看见这幅共享图景来自哪里。 +> 哪件事最能帮助我们达到下一个阶段目标？现在加入团队账号，还符合之前定下的方向吗？ -## Bearing 连接了什么 +Bearing 把你选定的工作放回同一份项目规划中。沿着一份 Map，你可以找到它对应的工作目标、要通过的阶段验收，以及做出决定时的依据。Agent 也能从这些来源出发，与你讨论继续推进、调整方向，还是另立一个目标。 -```text -你 + 你的 coding agent - ↕ - Bearing 项目治理 - ↕ -Matt-native Maps 与 Tickets + + +## Map 与 Effort 怎么对应？ -Portal 读取同一幅项目全貌 +在 Bearing 里，一项已确认要推进的工作称为 **Effort**。采用 Wayfinder 时，一份 Map 及其所在的工作范围，可以由一个 Effort 承接：Map 组织探索和决策，Effort 说明这项工作为什么值得做、服务于哪个阶段目标。 + +```text +项目方向（Roadmap） + └─ 阶段目标与验收（Milestone Gate） + ├─ 一项工作（Effort） + │ └─ Wayfinder Map 与相关任务 + └─ 另一项工作（Effort） + └─ Wayfinder Map 与相关任务 ``` -Bearing 负责长期项目治理：Project Summary、Roadmaps、Milestone Gates、Effort bindings、Authorities、Assets、Planning Reviews、Planning Audit，以及证据关系。 +Map 中的问题都想清楚了，后续开发可能才刚开始。Effort 会贯穿接下来的交付与验收，直到这项工作有明确的结论。 -你的 work-management adapter 继续负责 Maps、Tickets、依赖、claims、blockers 与 resolution。你的 executor 继续负责实现和验证。Bearing 连接这些层次，但不会伪装成它们的全部。 +哪些工作放进 Bearing，由你选择。Effort 也可以先被规划出来，或直接承接实施任务，不必都从 Map 开始。 -已经在使用 Matt Pocock 的 planning workflow？Bearing 设计上读取同一类本地 Markdown Map 与 Ticket 形状，因此你不需要把工作迁移进另一套 tracker，就能增加 governance 和 Portal orientation。 +## 沿用你熟悉的 Matt 工作流 -## Bearing 适合你吗？ +- **Wayfinder**：逐步理清未知问题，把决定留在 Map 中。 +- **规格与任务拆分 skills**：按需要，把已经想清楚的方案整理为 Spec，再拆成可交付的任务。 +- **执行工具或 agent**：完成实现与验证。 +- **Bearing**：把这些工作连接到项目方向、阶段目标和验收依据，并通过本地 Portal 展示出来。 -Bearing 很可能适合你，如果： +当前预览版支持 Matt 工作流的本地 Markdown Map、Spec 和 Ticket。你继续在原来的地方管理任务、依赖和状态。Portal 用于查看与追溯；调整项目规划时，仍然在 agent 对话中作出决定。 -- 你在跨越许多 sessions 的软件项目中使用 coding agents； -- 你希望新请求在开始前先和已接受方向对齐； -- 你已经使用，或愿意使用，受支持的 Matt-native 本地 Markdown Map 与 Ticket 工作流； -- 你想要本地仓库 truth、本地 Portal，以及无自动 telemetry； -- 你能接受 macOS-first 的 `0.x` Public Preview 和有文档说明的 breaking changes。 + -Bearing 目前可能不适合你，如果： +## 开始使用 -- 你的工作大多是一次性编码任务，几乎没有 durable context； -- 你想要的是 Kanban board、托管 issue tracker、自主项目经理，或通用记忆数据库； -- 你不愿使用受支持的本地 Markdown work-management adapter； -- 你需要 hosted multi-user、产品托管认证、cloud sync，或 public Internet Portal； -- 你今天就需要官方支持 Linux 或 Windows。 +准备好 macOS、Node.js 24.15.0 或更高版本，以及能够安装软件并接入 skill 的 coding agent。从一个正在推进的 Git 项目和一份真实的 Wayfinder Map 开始，最容易看出 Bearing 的作用。 -## Public Preview 支持范围 +### 1. 让 agent 安装 Bearing -| 范围 | Public Preview 支持 | -| --- | --- | -| 平台 | macOS | -| Node.js | Node.js 24.15.0 及以上；CI 验证 Node.js 24.15.0 与 26 | -| Work Management Adapter | Matt-native 本地 Markdown Maps 与 Tickets | -| Telemetry | 无。Bearing 不做 analytics、crash upload、repository upload 或 update polling。 | +把这段话交给 agent： -## Interactive browser sample +```text +请从 https://github.com/lagrangee/bearing 安装 Bearing，按照仓库的 Agent installation guide 核实并安装已发布版本，将 Bearing skill 接入你当前使用的 skill 目录。安装完成后先停下，项目设置稍后再做。 +``` -[打开 interactive browser sample](https://lagrangee.github.io/bearing/)。它是一个只使用固定 -mock Northstar 数据的 browser-only Portal demo。这个 demo 是 static sample，不是 hosted Bearing -project、real repository、canonical planning surface 或 product-value proof。它不启动本地 Portal -Host，不读取 repository，不调用 provider 或 API，不使用 analytics，也不持久化 browser state。 +[安装指南](docs/agent-installation.md)会让 agent 核实一个精确的已发布版本，并分别确认软件安装、skill 接入和项目设置。正常安装使用发布包。 -受支持的产品使用从[本地安装](#quickstart完成一次真实-alignment-loop)和 loopback Portal 开始。 -Demo 可用不代表安装成功。分享 Portal capture 或修改 private reachability 前，请阅读 -[data and security boundary](docs/data-and-security.zh-CN.md)。Demo 与 production Portal runtime -保持隔离，也不会进入 npm package。 +如果需要手动安装，先核实发布版本和包的身份，再运行： -## Feedback 与支持 +```bash +npx --yes @lagrangee/bearing@ install +``` + +安装程序会提示如何设置 PATH，不会修改 shell 配置。遇到问题可查看[入门指南](docs/getting-started.zh-CN.md)和[故障排查](docs/troubleshooting.zh-CN.md)。 -- 可通过 [Bug report](https://github.com/lagrangee/bearing/issues/new?template=bug_report.yml) 或 [Documentation problem](https://github.com/lagrangee/bearing/issues/new?template=documentation.yml) 提交可复现 bug 与可执行的文档问题。Blank Issues 默认关闭。 -- 安装、概念、工作流与故障排查问题请进入 [Q&A](https://github.com/lagrangee/bearing/discussions/categories/q-a)；体验、场景、痛点、建议及尚待成形的 feature ideas 请进入 [Ideas](https://github.com/lagrangee/bearing/discussions/categories/ideas)。 -- 疑似漏洞只能通过 [GitHub private vulnerability reporting](https://github.com/lagrangee/bearing/security/advisories/new) 私下报告，绝不能发布在公开 Issue 或 Discussion 中。 +### 2. 把一项真实工作放进项目规划 -Issues 与 Discussions 都是公开 GitHub 数据。请勿提交 tokens、secrets、private source、完整 planning state、真实 absolute repository paths 或未打码 screenshots。Bearing 不会自动上传 diagnostics；logs、diagnostics 与 repository excerpts 只有在你明确提交时才会被分享。社区支持为 best-effort，不提供 SLA；公开 feedback 也不代表排期或交付承诺。 +在目标项目中打开 agent，并指出你要使用的 Map： + +```text +请为这个项目设置 Bearing。我想把这份 Wayfinder Map 和相关工作连接到项目方向与阶段目标。先说明你建议纳入的范围，以及需要建立的最小规划，等我确认后再写入。 +``` -## Quickstart：完成一次真实 alignment loop +从项目说明、Roadmap、当前 Gate 和一个 Effort 开始就够了。先把一项真实工作连接起来，再按需要纳入更多工作。 -### 1. 让你的 Agent 安装 Bearing +### 3. 带着真实问题使用它 -把下面的 prompt 交给你的 Agent。Agent 可以按独立的 -[Agent 安装指南](docs/agent-installation.md)执行，不需要在本 README 中展开 implementation details。 +例如： ```text -请从 https://github.com/lagrangee/bearing 安装 Bearing。请遵循 repository 中的 Agent installation guide，使用已发布 package，把 Bearing skill 接入你的 Skill Directory，并在 repository setup 前停止。 +我想增加团队账号。请结合当前项目方向、已经做出的决定和正在推进的工作，检查这件事是否合适；有冲突就先摊开讨论。 ``` -#### Terminal fallback +第一次有用的结果，是你能看清新请求与项目方向的关系，并据此作出决定。 -如果 Agent 无法执行安装，请选择并验证一个 exact released version，再运行该 candidate 的显式 -installer： +### 4. 在 Portal 中查看整体 ```bash -npx @lagrangee/bearing@ install +bearing inspect project --repo . +bearing portal ``` -Install 会 stage 并验证一份完整 bundle，然后把它作为整体切换，或恢复上一份完整 bundle。它不会 -初始化 repository 或启动 Portal。裸 `bearing` 只显示简洁 help。显式 `bearing uninstall` 只移除 -Global Kit、canonical CLI 与当前已知的 owned Agent Surface links；它保留 Project Catalog 和 -所有 repository。Older candidate 与 Current Kit Unverifiable 都是 no-write outcomes；见 -[故障排查](docs/troubleshooting.zh-CN.md)。Successful install 会直接打印经典 PATH guidance，且 -不会写入或 source shell profile。 +打开终端打印的本机访问地址，可以查看项目概况、Roadmap、Gate、Effort、需要关注的问题，以及它们的来源。更多命令见 [CLI 使用说明](docs/cli.zh-CN.md)。 -高级用户和 agents 可以使用显式命令；见 [CLI reference](docs/cli.zh-CN.md)。 + -### 2. 选择一个真实项目 +## 适合谁？ -从一个真实 Git 仓库开始，这个仓库最好已经有、或准备使用受支持的本地 Markdown Map 与 Ticket 工作流。Bearing 在能把真实方向连接到真实工作时，最容易产生第一次价值；空白 toy repo 能证明的东西很少。 +如果你已经在用 Matt Pocock 的 skills，尤其是 Wayfinder，而且项目里有几项持续推进的工作，Bearing 值得一试。每份 Map 和任务清单都能读懂，却越来越难把握它们与项目整体的关系，是一个典型的使用场景。 -### 3. 让 Agent 设置 Bearing +一次性的小任务通常不需要这么多规划。当前产品也不提供托管任务系统、自动项目经理、通用记忆库、多人在线协作或云端同步。 -用你的 Agent 打开 repository，然后问： + -```text -为这个项目设置 Bearing。把现有的 Map 和 Tickets 用作工作上下文，并引导我建立最低限度的治理基线。 -``` +## 支持范围 -最低有用基线是： +| 项目 | 当前支持 | +| --- | --- | +| 操作系统 | macOS；暂不正式支持 Linux 和 Windows | +| Node.js | 24.15.0 或更高版本；CI 覆盖 24.15.0 和 26 | +| 工作管理 | Matt 工作流的本地 Markdown Map、Spec 和 Ticket | +| 使用数据收集 | 不采集使用统计，不上传崩溃信息或仓库内容，不自动轮询更新 | -- 一份当前 Project Summary； -- 一条 active Roadmap 和 focused Milestone Gate； -- 一个把现有 Map 或 Ticket scope 绑定到该 Gate 的 Effort。 +目前为 `0.x` 开源预览版，可能发生不兼容变更；相关变化会记录在文档中。 -每个被接受的方向仍然是人的决策。Repository Configuration 不应该只靠仓库文件自行推断 governance truth。 + -### 4. 带来一个真实请求 +## 先看看 Portal -问一件你接下来真的想做的事： +[打开交互演示](https://lagrangee.github.io/bearing/)，用固定的 Northstar 示例数据看看项目关系如何呈现。 -```text -开始之前，请根据当前方向、已接受决策和活跃工作检查这件事。如果存在冲突，先让我看见冲突，再采取行动。 -``` +演示完全在浏览器中运行，不读取你的仓库，不启动本地服务，不调用 provider 或 API，也不记录使用统计或保存浏览器状态。它展示的是虚构项目，不代表你的安装已经成功，也不进入 npm 发布包。实际使用从本地安装开始。 -当 agent 解释这个请求如何符合当前方向，或在实现前暴露实质冲突并给出明确决策路径时，第一次 alignment loop 就完成了。安装成功本身不是价值里程碑。 + -### 5. 检查当前项目 +## 数据、安全与共享 -```bash -bearing inspect project --repo . -bearing portal -``` +- 项目规划保存在仓库的 `.bearing/state/` 中，原生工作保存在选定的本地 Markdown 范围；`.bearing/cache` 中的读取缓存可以重建。 +- 安装文件和项目列表保存在本机的 Bearing 用户目录中。 +- 显式安装或检查更新时会访问软件包仓库。Bearing 不自动上传使用统计、崩溃信息或项目内容；反馈只会在你主动提交时发出。 +- Portal 会显示仓库的完整本地路径。分享截图或诊断信息前，请先去除私有内容并遮盖路径。 +- 本机直接访问 Portal 使用 HTTP，会话 cookie 不带 `Secure` 标记；重启前台服务会使原有会话失效。 +- 如果通过 Tailscale Serve 或自行管理的反向代理提供私有访问，需要自行负责加密、身份验证和访问控制。当前不支持无认证的公网访问。 +- Bearing 用于你信任的本地仓库，不提供文件系统隔离，也不保证能抵御恶意的并发文件修改。 + +改变访问方式或分享项目资料前，请阅读[数据与安全](docs/data-and-security.zh-CN.md)及[安全说明](SECURITY.md)。 + + -打开 Portal Host 打印的 loopback URL，检查 Project Summary、focused Roadmap 和 Gate、contributing Effort、Attention 与 source provenance。 +## 反馈与帮助 -## Local-first 数据与信任边界 +- 可复现的问题：[报告 bug](https://github.com/lagrangee/bearing/issues/new?template=bug_report.yml) 或[报告文档问题](https://github.com/lagrangee/bearing/issues/new?template=documentation.yml)。请使用对应模板。 +- 使用疑问与想法：[Q&A](https://github.com/lagrangee/bearing/discussions/categories/q-a) 和 [Ideas](https://github.com/lagrangee/bearing/discussions/categories/ideas)。 +- 疑似安全漏洞：通过 [GitHub 私密漏洞报告](https://github.com/lagrangee/bearing/security/advisories/new)提交，避免在公开 Issue 或 Discussion 中披露。 -- 仓库治理 truth 存在仓库的 Bearing state 和原生本地 Markdown work scope 中。 -- 用户级安装与 Project Catalog 数据存在用户的 Bearing home directory 中。 -- `.bearing/cache` 是 disposable projection data；source truth 仍在 canonical state 与 native work files 中。 -- Portal 面向 owner 的 Catalog API 与 UI 会显示 absolute repository roots，因此 screenshots 与用户主动分享的 diagnostics 可能暴露本地路径，分享前必须打码。 -- 直接 loopback Portal 使用 HTTP，因此它的 session cookie 不带 `Secure`；重启前台 Portal Host 会使 session 失效。 -- 私有 Tailscale Serve 或 owner-managed reverse proxy 可以提供私有 reachability，但 owner 负责 TLS、认证、访问控制与暴露边界。不支持 public unauthenticated Internet exposure。 -- Bearing 是本地 trusted-checkout 工具。它不是 filesystem sandbox，也不声称能防御恶意并发文件系统修改。 +Issues 和 Discussions 的内容公开可见。请勿提交密钥、私有源码、完整规划记录、真实仓库路径或未经遮盖的截图，只提供定位问题所需的最小脱敏片段。社区支持尽力而为，不承诺响应时限；提交反馈不代表相关工作已经排期。 -更多见 [Data and security](docs/data-and-security.zh-CN.md) 和 [SECURITY.md](SECURITY.md)。 + -## 学习、恢复与贡献 +## 文档与参与 -- [Getting started](docs/getting-started.zh-CN.md) -- [Everyday workflows](docs/everyday-workflows.zh-CN.md) -- [Data and security](docs/data-and-security.zh-CN.md) -- [Troubleshooting](docs/troubleshooting.zh-CN.md) -- [CLI reference](docs/cli.zh-CN.md) -- [Contributing](CONTRIBUTING.md) -- [Code of Conduct](CODE_OF_CONDUCT.md) -- [Third-party notices](THIRD_PARTY_NOTICES) +[入门指南](docs/getting-started.zh-CN.md) · [日常用法](docs/everyday-workflows.zh-CN.md) · [故障排查](docs/troubleshooting.zh-CN.md) · [CLI 使用说明](docs/cli.zh-CN.md) · [参与贡献](CONTRIBUTING.md) · [行为准则](CODE_OF_CONDUCT.md) · [第三方声明](THIRD_PARTY_NOTICES) -Bearing 采用 MIT License 开源。 +Bearing 按 MIT 协议开源。 diff --git a/tests/agent-installation-contract.test.ts b/tests/agent-installation-contract.test.ts index fa08450b..68c4793d 100644 --- a/tests/agent-installation-contract.test.ts +++ b/tests/agent-installation-contract.test.ts @@ -16,16 +16,16 @@ test("public READMEs give Humans one Agent-mediated installation entry and a ter expect(english).toContain("https://github.com/lagrangee/bearing"); expect(english).toContain("[Agent installation guide](docs/agent-installation.md)"); expect(english).toMatch(/Ask your Agent[\s\S]*Install Bearing/iu); - expect(english).toMatch(/Terminal fallback[\s\S]*npx @lagrangee\/bearing/iu); - expect(english).toContain("@ install"); + expect(english).toMatch(/terminal fallback[\s\S]*npx --yes @lagrangee\/bearing/iu); + expect(english).toContain("npx --yes @lagrangee/bearing@ install"); expect(english).not.toMatch(/maintenance wizard/iu); expect(english).not.toMatch(/Install[／/,、 ]+Update[／/,、 ]+Repair/iu); expect(chinese).toContain("https://github.com/lagrangee/bearing"); - expect(chinese).toContain("[Agent 安装指南](docs/agent-installation.md)"); - expect(chinese).toMatch(/让你的 Agent[\s\S]*安装 Bearing/u); - expect(chinese).toMatch(/Terminal fallback[\s\S]*npx @lagrangee\/bearing/iu); - expect(chinese).toContain("@ install"); + expect(chinese).toContain("[安装指南](docs/agent-installation.md)"); + expect(chinese).toMatch(/让 agent[\s\S]*安装 Bearing/iu); + expect(chinese).toMatch(/手动安装[\s\S]*npx --yes @lagrangee\/bearing/iu); + expect(chinese).toContain("npx --yes @lagrangee/bearing@ install"); expect(chinese).not.toMatch(/maintenance wizard/iu); expect(chinese).not.toMatch(/Install[／/,、 ]+Update[／/,、 ]+Repair/iu); }); diff --git a/tests/demo-pages-contract.test.ts b/tests/demo-pages-contract.test.ts index 7ec0ddce..ac596492 100644 --- a/tests/demo-pages-contract.test.ts +++ b/tests/demo-pages-contract.test.ts @@ -262,8 +262,8 @@ test("the demo footer uses the existing visual system without a one-off underlin test("the public docs keep the browser sample separate from the supported local Portal", async () => { for (const path of ["README.md", "README.zh-CN.md", "SECURITY.md"]) { const source = await readFile(join(repoRoot, path), "utf8"); - expect(source).toContain("browser-only"); - expect(source).toContain("mock"); + expect(source).toMatch(/browser-only|static browser sample|完全在浏览器中运行/u); + expect(source).toMatch(/mock|虚构项目/u); expect(source).toContain("docs/data-and-security"); } }); @@ -287,9 +287,9 @@ test("the public demo and bilingual docs expose the final public intake boundari for (const source of publicDocs) { for (const route of intakeRoutes) expect(source).toContain(route); - expect(source).toMatch(/public GitHub|公开 GitHub/iu); - expect(source).toMatch(/best-effort/iu); - expect(source).toMatch(/private vulnerability reporting/iu); + expect(source).toMatch(/public GitHub|公开 GitHub|Issues 和 Discussions 的内容公开可见/iu); + expect(source).toMatch(/best-effort|社区支持尽力而为/iu); + expect(source).toMatch(/private vulnerability reporting|私密漏洞报告/iu); } for (const source of publicDocs.slice(0, 2)) { expect(source).toContain(demoRoute);