@lloyal-labs/rig 2.0.1 → 3.0.0

package/LICENSE

@@ -0,0 +1,107 @@
+# Functional Source License, Version 1.1, Apache 2.0 Future License
+
+## Abbreviation
+
+FSL-1.1-Apache-2.0
+
+## Notice
+
+Copyright 2026 Lloyal Labs
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publish, and distribute the
+Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A "Permitted Purpose" is any purpose other than a Competing Use. A
+"Competing Use" means making the Software available to others in a
+commercial product or service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a Licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives
+of the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND,
+INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE,
+MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO
+THE SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
+DAMAGES, EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software
+under the Apache License, Version 2.0 that is effective on the second
+anniversary of the date we make the Software available. On or after that
+date, you may use the Software under the Apache License, Version 2.0, in
+which case the following will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not
+use this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+See the License for the specific language governing permissions and
+limitations under the License.

package/LICENSE-FAQ.md

@@ -0,0 +1,256 @@
+# Licensing FAQ
+
+> Canonical version at https://docs.lloyal.ai/licensing/faq.
+> This file is a synced copy. Edit the canonical source and re-run
+> `scripts/sync-license-faq.sh` in lloyal-sdk to update all copies.
+
+
+**You can build and sell commercial products using HDK.**
+
+> HDK is free to build products with; it is not free to become the
+> replacement HDK platform.
+
+That single sentence is the entire restriction reduced to one line. The rest
+of this page is illustration.
+
+## The short version
+
+HDK 3.0 runtime packages — `liblloyal`, `lloyal-node`, and the lloyal-sdk
+packages (`agents`, `sdk`, `rig`, `apps/corpus`, `apps/web`) — are
+source-available under **FSL-1.1-Apache-2.0** (the Functional Source License,
+Apache 2.0 future grant). FSL is a [Fair Source](https://fair.io) license.
+
+Each version converts to Apache 2.0 two years after its release. The
+restriction during those two years is narrow: **you cannot offer a competing
+HDK runtime, a managed HDK service, or an alternative HDK App distribution
+channel.** Everything else — commercial use, redistribution, modification,
+sale, embedding in shipped products — is freely permitted.
+
+The reason the channel restriction exists is consumer-protective: every App
+listed on `apps.lloyal.ai` is reviewed by Lloyal Labs for tool-safety,
+manifest conformance, and signature provenance before publication. Pinning
+the App ecosystem to one verified channel keeps the AI-safety review meaningful
+(consumers can rely on a single trust boundary) and prevents protocol
+fragmentation (an App that works on one harness works on every harness).
+
+The `harness.dev` CLI and `hdk-create-app` scaffolder are licensed under
+**Apache 2.0** (unrestricted). They're not part of the runtime stack.
+
+## Can I ship a commercial product built on HDK?
+
+**Yes.** This is the question everyone has and the answer is straightforward.
+Concretely:
+
+- **Shipping a paid intelligent inbox app to consumers** — permitted ✅
+- **Selling an Excel-with-AI desktop app to enterprises** — permitted ✅
+- **Embedding HDK in a medical device sold commercially** — permitted ✅
+- **A consulting firm building a custom intelligent harness for a Fortune
+  500 client, charging $500K for the engagement, deploying on client
+  infrastructure** — permitted ✅
+- **An indie dev shipping a paid productivity app on the Mac App Store** —
+  permitted ✅
+- **An OEM shipping HDK inside an infotainment system or industrial device**
+  — permitted ✅
+- **A startup building an end-user product on top of HDK** — including
+  vertical research apps, workflow tools, and agent applications — permitted
+  ✅, *as long as the product is not offering HDK itself as a substitute
+  runtime, managed HDK service, or competing App distribution channel*.
+- **A research lab using HDK in published academic work** — permitted ✅
+- **Forking HDK on GitHub to learn, modify, demo, or contribute** — permitted ✅
+- **Running HDK internally inside your company for any business use** —
+  permitted ✅
+
+If you are building something *with* HDK, you are almost certainly fine.
+
+## What is actually restricted?
+
+The restriction is narrow and specific: **don't become the replacement
+platform vendor**. Concretely:
+
+- **AWS / Google / Microsoft launching "Bedrock Managed HDK" or "Vertex HDK"
+  as a hosted runtime service** — restricted ❌
+- **A competitor publishing "OpenHDK" as a forked harness runtime under a
+  different name** — restricted ❌
+- **A clean-room reimplementation of the HDK runtime in Python / Rust / Go
+  intended as a drop-in replacement** — restricted ❌ (Competing Use doesn't
+  require forking source code — a reimplementation that competes is the
+  same problem)
+- **Launching `apps.competitor.com` as an alternative HDK App distribution
+  channel** — restricted ❌
+- **Offering "managed HDK hosting" or "HDK-as-a-Service" as a competing
+  SaaS** — restricted ❌
+- **A hosted orchestration service exposing HDK-compatible APIs as a
+  substitute for the HDK runtime** — restricted ❌
+
+Notice the pattern: every restricted scenario is "become the platform
+vendor," not "build products with HDK." If your project doesn't compete
+directly with the HDK runtime or its distribution channel, FSL doesn't
+affect you.
+
+## Why does the LICENSE list four narrow Permitted Purposes then?
+
+You may read the FSL LICENSE and see this section:
+
+> Permitted Purposes specifically include using the Software:
+> 1. for your internal use and access;
+> 2. for non-commercial education;
+> 3. for non-commercial research; and
+> 4. in connection with professional services that you provide to a
+>    Licensee using the Software in accordance with these Terms and
+>    Conditions.
+
+A careful first reading can mistake this list for the *exclusive* set of
+permitted uses — leading to the (incorrect) conclusion that commercial
+product distribution is prohibited.
+
+It isn't. **The operative definition is broader.** Earlier in the same
+section, the license states:
+
+> A "Permitted Purpose" is any purpose other than a Competing Use.
+
+The four enumerated items are **illustrative examples** added because those
+specific cases are ones a careful reader might otherwise hesitate about
+("is research permitted? is consulting permitted?"). The four items are
+additive clarifications, not a closing of the open-ended definition.
+
+Sentry, who authored FSL and uses it on their own software, [confirms this
+explicitly in their FAQ](https://fsl.software):
+
+> "You can do anything with FSL software except undermine its producer. You
+> can run it for almost all purposes, study it, modify it, and distribute
+> your changes…"
+
+If the license felt restrictive on first read, that's a documented
+[FSL adoption hazard](https://fair.io) — many developers hit the same wall.
+The answer is to read the "any purpose other than a Competing Use" line as
+the operative definition and treat the four enumerated items as examples,
+not as a closed list.
+
+## Will it become Apache 2.0?
+
+**Yes — automatically, on a per-version schedule.** Each released version of
+the runtime stack converts to Apache 2.0 exactly two years after its release
+date. The conversion is irrevocable and written into the license text — it's
+not a promise from Lloyal Labs, it's a contractual clause.
+
+For example: if `lloyal-sdk @lloyal-labs/lloyal-agents` v3.0.0 is released
+on 2026-06-01, that exact version becomes available under Apache 2.0 on
+2028-06-01. Any consumer can elect to use that version under Apache 2.0
+from that date forward — Lloyal Labs takes no action; the grant is
+automatic.
+
+New versions released after v3.0.0 start their own two-year clock from
+their own release dates. There is no single global Change Date.
+
+## Is this OSI-approved open source?
+
+**No, and we want to be honest about that.** FSL is not OSI-approved
+because the OSI definition of open source (clause 6, "No Discrimination
+Against Fields of Endeavor") does not permit restrictions on specific
+use cases. FSL restricts Competing Use. That restriction takes it out of
+strict OSI compliance.
+
+FSL falls under the [Fair Source](https://fair.io) classification —
+source-available licenses that are explicitly developer-friendly:
+commercial use permitted, free redistribution, eventual open-source
+conversion. Fair Source is a more developer-friendly framing than the
+generic "source-available" label, which has been tainted by the
+SSPL / Elastic / MongoDB relicensing trauma cycles.
+
+What this means practically:
+
+- **You can read the source.** ✅
+- **You can modify it.** ✅
+- **You can sell products built with it.** ✅
+- **You can redistribute it (with the same FSL terms).** ✅
+- **It will be Apache 2.0 in two years.** ✅
+- Some enterprise procurement policies that strictly require OSI-approved
+  licenses will require an exception for this. We're working on making
+  that exception easy to grant.
+
+## Why FSL specifically — why not stay Apache?
+
+HDK 3.0 introduces installable HDK Apps. Every App declares against a
+specific App protocol — the bytes-locked intro, catalog format,
+tool-selection rule, and boundary marker that the runtime renders into
+the spine. Your App's reliability depends on every HDK runtime your users
+install agreeing on the same protocol.
+
+Under a permissive license alone, the protocol is forkable. A
+well-resourced redistributor could fork the runtime, modify the protocol
+surface, and distribute a variant under a different name with captive
+distribution. App developers then face a fragmented ecosystem: target one
+protocol, target both, or pick the bigger distribution and abandon the
+others. The cost of that split is paid by App developers in testing
+burden, divergent behavior, and reliability degradation across runtimes.
+
+FSL's two-year Competing Use restriction is shaped to block that
+fragmentation specifically. After the conversion, anyone can build
+whatever they want — by which time the protocol has had enough time to
+stabilize through ecosystem use and the protection is no longer the load-
+bearing thing keeping it coherent.
+
+For the longer treatment of this argument, see
+[Why FSL](./why-fsl).
+
+We could have used Apache 2.0 and tried to protect only the channel via
+terms-of-service. We could have written a custom license. We chose
+standard FSL because it's:
+
+- **Off-the-shelf** — no bespoke license review at every adopter
+- **Recognizable** — Sentry, PowerSync, and others use it
+- **Documented** — the FAQ, definitions, and edge cases have been
+  litigated publicly
+- **Time-bounded** — the protocolual Apache 2.0 conversion is the answer
+  to the "is this just source-available forever?" critique
+- **Pre-launch** — relicensing at HDK 3.0 launch is structurally
+  different from MongoDB / Elastic / HashiCorp relicensing under an
+  existing installed base, which is what causes the backlash cycle
+
+## What about the lloyal stack — what's under FSL and what's not?
+
+| Component | License | Why |
+|---|---|---|
+| `liblloyal` (C++ engine) | FSL-1.1-Apache-2.0 | Native primitives the runtime is built on |
+| `lloyal-node` (N-API binding) | FSL-1.1-Apache-2.0 | The binding that lets Effection drive llama.cpp |
+| `@lloyal-labs/lloyal-agents` | FSL-1.1-Apache-2.0 | Runtime framework |
+| `@lloyal-labs/lloyal-sdk` | FSL-1.1-Apache-2.0 | Runtime framework |
+| `@lloyal-labs/rig` | FSL-1.1-Apache-2.0 | Runtime framework — holds the App protocol |
+| `@lloyal-labs/corpus`, `@lloyal-labs/web` | FSL-1.1-Apache-2.0 | Reference Apps shipped in-tree |
+| **`@lloyal-labs/harness-cli` (the `harness.dev` CLI)** | **Apache 2.0** | Scaffolder — unrestricted for scaffolding new harnesses and Apps |
+| **`hdk-create-app`** (when shipped) | **Apache 2.0** | Scaffolder — same as above |
+| `llama.cpp` (vendored dependency) | MIT (unchanged) | External upstream library; we don't relicense their code |
+
+## Can I contribute to HDK?
+
+**Yes.** Contributions are welcome under the same FSL license terms. If you
+submit a PR, you're granting Lloyal Labs the right to distribute your
+contribution under FSL-1.1-Apache-2.0 (and automatically under Apache 2.0
+two years after each release that includes it). The CONTRIBUTING file in
+each repo has the details.
+
+## I have a use case that's borderline — who do I ask?
+
+Email [legal@lloyal.ai](mailto:legal@lloyal.ai) (or open a discussion in the repo). The runtime
+team will help you confirm whether your use case falls under Permitted
+Purpose or Competing Use. We'd rather give you a quick yes than have you
+worry about it.
+
+## Further reading
+
+- [FSL official site](https://fsl.software) — Sentry's canonical FSL
+  resources and FAQ
+- [Fair Source](https://fair.io) — the category FSL belongs to
+- [The FSL template, instantiated for each repo](./fsl-template)
+- [Why we chose FSL over BSL, Apache, or a custom license](./why-fsl)
+
+## Is there a safe harbor for building products with the HDK?
+
+Yes. The [Lloyal Harness Builder Grant](https://github.com/lloyal-ai/hdk/blob/main/GRANT.md)
+irrevocably guarantees that building, selling, and hosting Harnesses and Apps
+is a Permitted Purpose and never a Competing Use — even products that compete
+head-on with Lloyal's own (including reasoning.run). Only three uses remain
+restricted: offering the HDK itself as a developer framework, hosting the HDK
+as-a-service for third-party developers, and operating a general-purpose App
+distribution channel. Private/internal App distribution and your Harness's
+own plugin system are explicitly permitted.

package/README.md

@@ -44,38 +44,49 @@ An agent that greps with a narrow pattern and gets 0 matches will broaden the pa
 
 Depth scales with `maxTurns`. At 2 turns, agents do single-shot retrieval. At 6 turns, agents do 3–4 rounds of iterative refinement. At 20 turns, agents go deep — following citation chains, cross-referencing claims, building evidence maps. The quality difference is in the later tool call inputs.
 
-## Sources
+## Sources via the HDK 3.0 App protocol
 
-`@lloyal-labs/rig` provides two `Source` implementations (extending the base class from `lloyal-agents`):
+`@lloyal-labs/rig` is the framework layer; concrete `Source` implementations
+ship as separate **apps** under the HDK 3.0 App protocol (RFC §5):
 
-**`CorpusSource`** — local files with grep, semantic search, read_file, and recursive delegation. Agents investigate a knowledge base by pattern matching, reading sections in context, and spawning sub-agents for deeper investigation.
+**`@lloyal-labs/corpus-app`** — local files with grep, semantic search,
+read_file, and recursive delegation. Agents investigate a knowledge base by
+pattern matching, reading sections in context, and spawning sub-agents for
+deeper investigation.
 
-**`WebSource`** — web search via [Tavily](https://tavily.com), page fetching with attention-based content extraction, and recursive delegation. `BufferingFetchPage` wraps fetch results — full content goes to the agent for reasoning, while a parallel buffer stores content for post-research reranking. Content extraction uses an ephemeral fork to attend over the fetched page and extract summary + links via grammar-constrained generation, then prunes the fork — zero net KV cost per extraction.
+**`@lloyal-labs/web-app`** — web search via [Tavily](https://tavily.com) (or
+keyless DuckDuckGo fallback), page fetching with attention-based content
+extraction, and recursive delegation. `BufferingFetchPage` wraps fetch
+results — full content goes to the agent for reasoning, while a parallel
+buffer stores content for post-research reranking. Content extraction uses
+an ephemeral fork to attend over the fetched page and extract summary +
+links via grammar-constrained generation, then prunes the fork — zero net
+KV cost per extraction.
 
-Sources are composable. A pipeline can use one source, both, or custom implementations:
+Apps are composable through the registry:
 
 ```typescript
 import {
-  CorpusSource,
-  WebSource,
-  TavilyProvider,
+  createAppRegistry,
+  createInMemoryConfigStore,
 } from "@lloyal-labs/rig";
-import { loadResources, chunkResources } from "@lloyal-labs/rig/node";
-
-const sources = [];
-
-if (corpusDir) {
-  const resources = loadResources(corpusDir);
-  const chunks = chunkResources(resources);
-  sources.push(new CorpusSource(resources, chunks));
-}
-
-if (process.env.TAVILY_API_KEY) {
-  sources.push(new WebSource(new TavilyProvider()));
-}
+import { RerankerCtx } from "@lloyal-labs/lloyal-agents";
+import { createWebApp } from "@lloyal-labs/web-app";
+import { createCorpusApp } from "@lloyal-labs/corpus-app";
+
+yield* RerankerCtx.set(reranker);
+const configStore = createInMemoryConfigStore();
+if (tavilyKey) yield* configStore.set("web", { tavilyKey });
+if (corpusDir) yield* configStore.set("corpus", { corpusPath: corpusDir });
+const registry = yield* createAppRegistry({ configStore });
+
+if (corpusDir) yield* registry.enable(createCorpusApp);
+yield* registry.enable(createWebApp);  // keyless fallback if no tavilyKey
 ```
 
-When multiple sources are used, they run sequentially — each source gets the full KV budget. After source N completes, its inner branches are pruned and KV is freed for source N+1.
+When multiple apps are enabled, their sources run sequentially — each gets
+the full KV budget. After source N completes, its inner branches are pruned
+and KV is freed for source N+1.
 
 ### Cross-encoder reranker — four scoring roles
 
@@ -84,7 +95,7 @@ The reranker (a small cross-encoder GGUF — Qwen3-Reranker-0.6B is the recommen
 - **`scoreEntailmentBatch`** — texts vs. the original query. Boundary entailment for retrieved content.
 - **`scoreRelevanceBatch`** — dual-score `min(toolQueryScore, originalQueryScore)`. Used in exploit mode when KV pressure tightens focus.
 - **`scoreSimilarityBatch`** — texts vs. an arbitrary reference. Powers echo detection at delegation boundaries (the agent's own task as reference).
-- **`shouldProceed`** — floor gate. Default `_entailmentFloor = 0.25`.
+- **`shouldProceed`** — floor gate. Default `_entailmentFloor = 0` (logit-diff space: `≥ 0` ⇒ model prefers "yes" over "no"; subclasses may tighten or loosen).
 
 One model, four roles. The reranker is RIG infrastructure, not a fetch optimization.
 
@@ -126,32 +137,38 @@ Agents that get cut by context pressure (their tool results exceeded KV headroom
 
 Full architectural walkthrough: [RIG Pipeline reference](https://docs.lloyal.ai/reference/rig/pipeline).
 
-## Tools
+## Framework tools
+
+| Tool           | Description                                                                  |
+| -------------- | ---------------------------------------------------------------------------- |
+| `ReportTool`   | Terminal tool — agents call this to submit findings                          |
+| `PlanTool`     | Grammar-constrained query decomposition with intent classification           |
+| `DelegateTool` | Generic recursive-delegation tool — agent calls it to spawn a sub-agent pool |
 
-### Corpus tools
+App-scoped tools (`web_search`, `fetch_page`, `search`, `read_file`,
+`grep`) live in their owning app — `@lloyal-labs/web-app`,
+`@lloyal-labs/corpus-app`, and so on — installed via
+`harness.dev install lloyal/<name>`. Build your own app with
+`harness.dev app <name>`.
 
-| Tool           | Description                                                             |
-| -------------- | ----------------------------------------------------------------------- |
-| `SearchTool`   | Semantic search over corpus chunks via reranker scoring                 |
-| `GrepTool`     | Exhaustive regex pattern matching across all files                      |
-| `ReadFileTool` | Read file content at specified line ranges, tracks per-agent read state |
-| `ReportTool`   | Terminal tool — agents call this to submit findings                     |
+## Search providers
 
-### Web tools
+The `lloyal/web` app ships with two interchangeable `SearchProvider`
+implementations exposed from rig so apps can swap providers without
+vendoring an API client:
 
-| Tool            | Description                                                     |
-| --------------- | --------------------------------------------------------------- |
-| `WebSearchTool` | Web search via configurable provider (`TavilyProvider` included) |
-| `FetchPageTool` | Fetch URL, extract article text via Readability                 |
+| Provider                           | Description                                                       |
+| ---------------------------------- | ----------------------------------------------------------------- |
+| `TavilyProvider`                   | Tavily-backed web search (key from constructor or env)            |
+| `createKeylessSearchProvider()`    | Keyless DuckDuckGo fallback with built-in pacer + circuit breaker |
 
-### Pipeline tools
+## Node-only surface (`@lloyal-labs/rig/node`)
 
-| Tool                   | Description                                                                  |
-| ---------------------- | ---------------------------------------------------------------------------- |
-| `PlanTool`             | Grammar-constrained query decomposition with intent classification           |
-| `DelegateTool`         | Generic recursive-delegation tool — agent calls it to spawn a sub-agent pool |
-| `createTools(opts)`    | Build corpus toolkit from resources, chunks, and reranker                    |
-| `createReranker(path)` | (`/node` subpath) Semantic reranker for chunk scoring and passage selection  |
+| Symbol                 | Description                                                                |
+| ---------------------- | -------------------------------------------------------------------------- |
+| `createReranker(path)` | Semantic reranker — runs the cross-encoder GGUF against text batches       |
+| `loadResources(dir)`   | Walk a directory into `Resource[]` for corpus apps                         |
+| `chunkResources(rs)`   | Split resources into `Chunk[]` for tokenization + reranker scoring         |
 
 ### `DelegateTool`
 
@@ -174,43 +191,32 @@ const delegate = new DelegateTool({
 
 The agent sees `web_research` (or whatever `name` you give it) as a callable tool. Calling it spawns parallel sub-agents that recurse into the corpus or web. The deeper an investigation goes, the richer the attention state at depth — and the cost of inheritance is zero.
 
-## Custom Sources
+## Building your own App
 
-Extend `Source` from `lloyal-agents` to create custom sources:
+Apps are the HDK 3.0 unit of distribution. An App bundles a
+`Source` + `Tool[]` + `skill.eta` + `app.json` manifest and gets
+shipped to consumers via the signed channel at `apps.lloyal.ai`.
 
-```typescript
-import { Source } from "@lloyal-labs/lloyal-agents";
-import type { Tool } from "@lloyal-labs/lloyal-agents";
-
-class DatabaseSource extends Source<DatabaseContext, Row> {
-  readonly name = "database";
-
-  get tools(): Tool[] {
-    return this._tools;
-  }
-
-  *bind(ctx: DatabaseContext) {
-    // Set up tools, reranker, scorer state
-    this._tools = [
-      new QueryTool(/* ... */),
-      new SchemaInspectTool(/* ... */),
-    ];
-  }
-
-  getChunks(): Row[] {
-    return this._results; // buffered for post-research reranking
-  }
-}
+Scaffold one with:
+
+```bash
+npx harness.dev app my-app
 ```
 
-The `bind()` lifecycle receives a context with reranker and scorer plumbing. Your tools call `agentPool` or `useAgent` internally for recursive patterns — same primitives the built-in sources use.
+The scaffold ships with a working source + two tools calling
+Wikipedia's REST API as a runnable demo backend. Replace the tool
+bodies with your real backend, keep the schemas, and you're a
+`harness.dev publish` away from being installable in any HDK
+harness.
 
-See [custom sources](https://docs.lloyal.ai/reference/rig/custom-sources) for the full contract.
+See [docs.lloyal.ai/build-an-app](https://docs.lloyal.ai/build-an-app)
+for the full App protocol contract.
 
 ## Documentation
 
-Full positioning, source contract, reranker mechanics, and pipeline patterns at [docs.lloyal.ai](https://docs.lloyal.ai).
+Full positioning, App protocol, reranker mechanics, and pipeline
+patterns at [docs.lloyal.ai](https://docs.lloyal.ai).
 
 ## License
 
-Apache-2.0
+See [LICENSE](./LICENSE) (Functional Source License 1.1 — Apache 2.0 Future License).