task: Docs Housekeeping

CLAUDE.md

@@ -27,6 +27,42 @@
 
 The project uses pnpm workspaces and NX for monorepo management with packages organized in `packages/` directory, services in the `services/` directory, and end-to-end tests in the `tests/` directory
 
+## Documentation (`docs/`)
+
+The `docs/` folder contains **GitBook documentation** that is synced to [docs.learncard.com](https://docs.learncard.com). These docs follow the **Diátaxis framework**, which organizes documentation into four distinct types:
+
+### Diátaxis Structure
+
+| Type | Purpose | Location |
+|------|---------|----------|
+| **Tutorials** | Learning-oriented, hands-on lessons | `docs/tutorials/` |
+| **How-To Guides** | Task-oriented, step-by-step recipes | `docs/how-to-guides/` |
+| **Reference** | Information-oriented, technical descriptions | `docs/sdks/` |
+| **Explanation** | Understanding-oriented, conceptual discussion | `docs/core-concepts/` |
+
+### Key Files
+
+- `docs/README.md` — Landing page (What is LearnCard?)
+- `docs/SUMMARY.md` — Table of contents / sidebar navigation (GitBook uses this)
+- `docs/quick-start/` — Getting started guides
+
+### Editing Guidelines
+
+- **GitBook syntax**: Docs use GitBook-flavored markdown with special directives like `{% tabs %}`, `{% hint %}`, `{% content-ref %}`
+- **Code snippets**: Must be accurate and runnable. Use `@learncard/init` for initialization (not `@learncard/core`)
+- **Links**: Internal links use relative paths. GitBook handles `/broken/pages/` placeholders automatically
+- **Context URLs**: Use current versions (e.g., `https://ctx.learncard.com/boosts/1.0.3.json`)
+- **API patterns**: Use `learnCard.invoke.*` for methods, `learnCard.id.did()` for DID access
+- **Simplicity**: Avoid jargon. Spell out acronyms on first use. Keep examples minimal
+
+### Testing Doc Changes
+
+Docs are not programmatically tested. When editing:
+
+1. Verify code snippets match the actual SDK API
+2. Check that imports reference the correct packages
+3. Ensure `await` is used with async operations like `addPlugin()`
+
 ## LearnCard Plugin System
 
 LearnCard uses a modular plugin system to extend functionality in a composable way. Understanding this architecture is critical for development.

docs/README.md

@@ -11,7 +11,7 @@ Whether you're building edtech apps, issuing credentials, or designing learner-f
 ### Why Use LearnCard?
 
 * **Portable**: Credentials travel with the learner—not locked into one system.
-* **Consentful**: Learners control who sees what, and when.
+* **Consent-Driven**: Learners control who sees their data, and when.
 * **Open**: Built on interoperable, community-driven standards.
 * **Developer-Friendly**: Plug in easily to existing apps with modern APIs and tools.
 
@@ -33,24 +33,25 @@ LearnCard is already used to:
 
 This documentation is your guide to building with LearnCard. Here’s how to navigate it:
 
-* [**Core Concepts**](/broken/pages/Wc9n2nCjCt5tw1mOV0fz): Understand the philosophy and structure of the ecosystem.
-* [**Use Cases & Possibilities**](introduction/use-cases-and-possibilities.md): Explore real-world implementations.
-* [**Quick Start**](/broken/pages/d2FIDNQNWgVkGckv2wh2): Go from zero to integrated in minutes.
-* [**Tutorials**](/broken/pages/Y9wXsPvJ08m2dhSpoAPZ): Learn by building key example projects with LearnCard SDK and APIs. 
-* [**How-To Guides**](/broken/pages/Y9wXsPvJ08m2dhSpoAPZ)**:** Step-by-step recipes for with key workflows and integrations.
-* [**SDK & API Reference**](/broken/pages/2CFJ0iVopfhxEzxav7hh): Deep dive into our SDKs and REST APIs.
-* [**Development**](/broken/pages/tg4rp5RrLHvu021foafS): Links to contributing, roadmap, etc.
+* [**Quick Start**](quick-start/your-first-integration.md): Go from zero to integrated in minutes.
+* [**Tutorials**](tutorials/create-a-credential.md): Learn by building — create credentials, boosts, and connected apps.
+* [**How-To Guides**](how-to-guides/send-credentials.md): Step-by-step recipes for common workflows.
+* [**Core Concepts**](core-concepts/credentials-and-data/verifiable-credentials-vcs.md): Understand credentials, DIDs, consent, and the plugin system.
+* [**SDK Reference**](sdks/learncard-core/README.md): Deep dive into our SDK and APIs.
 
 If you're new, start with [**Your First Integration**](quick-start/your-first-integration.md) under the Quick Start section.
 
 ***
 
 ### How to Implement LearnCard
 
-1. **Pick your flow**: Do you want to issue credentials, verify them, or manage a user's digital wallet?
-2. [**Install the SDK**](sdks/learncard-core/): Use the `@learncard/core` SDK, or interact via our APIs.
-3. **Use open schemas**: LearnCard supports OBv3, CLR, LTI, and more—no need to reinvent standards.
-4. **Add advanced features**: Selective disclosure, zero-knowledge proofs, guardianship models, bots, and more.
+1. **Pick your flow**: Issue credentials, verify them, or manage a user's wallet.
+2. **Install the SDK**: 
+   ```bash
+   npm install @learncard/init
+   ```
+3. **Use open standards**: LearnCard supports [Open Badges 3.0](https://www.imsglobal.org/spec/ob/v3p0/), W3C Verifiable Credentials, and more.
+4. **Scale up**: Add consent flows, network features, and advanced cryptography as needed.
 
 Whether you're building a web app, mobile experience, backend service, or bot, LearnCard has the primitives and integrations to make it seamless.
 
@@ -60,7 +61,7 @@ Whether you're building a web app, mobile experience, backend service, or bot, L
 
 This stack was built by developers, for developers. It supports open standards and real-world interoperability from day one. We’re glad you’re here—let’s build a more learner-friendly future together.
 
-### Comments, Questions, or Palpitations of the Heart?
+### Questions or Feedback?
 
 The best way to start engaging in the community is to participate in our [Github Discussions](https://github.com/learningeconomy/LearnCard/discussions): 
 

docs/SUMMARY.md

@@ -92,26 +92,7 @@
           spec: learn-cloud-storage-openapi
     ```
   * [xAPI Reference](sdks/learncloud-storage-api/xapi-reference.md)
-* [LearnCard App API](sdks/learncard-app-api.md)
 * [Plugins](sdks/official-plugins/README.md)
-  * [Crypto](sdks/official-plugins/crypto.md)
-  * [DIDKit](sdks/official-plugins/didkit.md)
-  * [DID Key](sdks/official-plugins/did-key.md)
-  * [Dynamic Loader](sdks/official-plugins/dynamic-loader.md)
-  * [VC](sdks/official-plugins/vc/README.md)
-    * [Expiration Sub-Plugin](sdks/official-plugins/vc/expiration-sub-plugin.md)
-  * [VC-Templates](sdks/official-plugins/vc-templates.md)
-  * [VC-API](sdks/official-plugins/vc-api.md)
-  * [Ceramic](sdks/official-plugins/ceramic.md)
-  * [IDX](sdks/official-plugins/idx.md)
-  * [VPQR](sdks/official-plugins/vpqr.md)
-  * [Ethereum](sdks/official-plugins/ethereum.md)
-  * [CHAPI](sdks/official-plugins/chapi.md)
-  * [LearnCard Network](sdks/official-plugins/learncard-network.md)
-  * [LearnCloud](sdks/official-plugins/learncloud.md)
-  * [LearnCard](sdks/official-plugins/learncard.md)
-  * [Simple Signing](sdks/official-plugins/simple-signing.md)
-  * [Claimable Boosts](sdks/official-plugins/claimable-boosts.md)
 * [LearnCard CLI](sdks/learncard-cli.md)
 
 ## 🧠 Core Concepts

docs/core-concepts/credentials-and-data/getting-started-with-boosts.md

@@ -38,7 +38,7 @@ const basicBoostCredential = {
   "@context": [
     "https://www.w3.org/2018/credentials/v1",
     "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.1.json",
-    "https://ctx.learncard.com/boosts/1.0.0.json",
+    "https://ctx.learncard.com/boosts/1.0.3.json",
   ],
   "credentialSubject": {
     "achievement": {
@@ -213,7 +213,7 @@ const courseCompletionBadge = {
   "@context": [
     "https://www.w3.org/2018/credentials/v1",
     "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.1.json",
-    "https://ctx.learncard.com/boosts/1.0.0.json",
+    "https://ctx.learncard.com/boosts/1.0.3.json",
   ],
   "credentialSubject": {
     "achievement": {
@@ -271,7 +271,7 @@ const professionalCertification = {
   "@context": [
     "https://www.w3.org/2018/credentials/v1",
     "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.1.json",
-    "https://ctx.learncard.com/boosts/1.0.0.json",
+    "https://ctx.learncard.com/boosts/1.0.3.json",
   ],
   "credentialSubject": {
     "achievement": {
@@ -355,7 +355,7 @@ const credentialWithEvidence = {
   "@context": [
     "https://www.w3.org/2018/credentials/v1",
     "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.1.json",
-    "https://ctx.learncard.com/boosts/1.0.0.json",
+    "https://ctx.learncard.com/boosts/1.0.3.json",
   ],
   "credentialSubject": {
     "achievement": {

docs/how-to-guides/connect-systems/connect-a-game.md

@@ -316,7 +316,7 @@ export async function getOrCreateAdditionL1Boost(): Promise<string> {
     if (additionL1BoostUri) return additionL1BoostUri;
     const learnCard = await getGameLearnCard();
     const badgeTemplate = { /* ... Define your badge VC structure ... */ 
-        "@context": ["https://www.w3.org/2018/credentials/v1", "https://purl.imsglobal.org/spec/ob/v3p0/context.json", "https://ctx.learncard.com/boosts/1.0.0.json"],
+        "@context": ["https://www.w3.org/2018/credentials/v1", "https://purl.imsglobal.org/spec/ob/v3p0/context.json", "https://ctx.learncard.com/boosts/1.0.3.json"],
         type: ["VerifiableCredential", "OpenBadgeCredential", "BoostCredential"],
         name: ADDITION_L1_BOOST_NAME,
         credentialSubject: {
@@ -376,7 +376,7 @@ export async function awardAdditionLevel1Badge(internalPlayerId: string, playerN
         const boostUriToIssue = await getOrCreateAdditionL1Boost();
 
         const credentialForPlayer = {
-            "@context": ["https://www.w3.org/2018/credentials/v1", "https://purl.imsglobal.org/spec/ob/v3p0/context.json", "https://ctx.learncard.com/boosts/1.0.0.json"],
+            "@context": ["https://www.w3.org/2018/credentials/v1", "https://purl.imsglobal.org/spec/ob/v3p0/context.json", "https://ctx.learncard.com/boosts/1.0.3.json"],
             id: "urn:uuid:" + randomUUID(),
             type: ["VerifiableCredential", "OpenBadgeCredential", "BoostCredential", "AchievementCredential"],
             issuer: learnCard.id.did(), // Game's DID

docs/how-to-guides/connect-systems/connect-a-website.md

@@ -312,7 +312,7 @@ export async function getOrCreateJsFundamentalsBoost(): Promise<string> {
         "@context": [
             "https://www.w3.org/2018/credentials/v1",
             "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.1.json", // Open Badges context
-            "https://ctx.learncard.com/boosts/1.0.0.json" // LearnCard Boosts context
+            "https://ctx.learncard.com/boosts/1.0.3.json" // LearnCard Boosts context
         ],
         type: ["VerifiableCredential", "OpenBadgeCredential", "BoostCredential"],
         name: JS_FUNDAMENTALS_BOOST_NAME, // Name of the credential instances
@@ -396,7 +396,7 @@ export async function issueJsBadgeToUser(internalUserId: string, userFullName: s
             "@context": [ // Contexts from your Boost template are often inherited or merged
                 "https://www.w3.org/2018/credentials/v1",
                 "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.1.json",
-                "https://ctx.learncard.com/boosts/1.0.0.json"
+                "https://ctx.learncard.com/boosts/1.0.3.json"
             ],
             id: "urn:uuid:" + randomUUID(), // Unique ID for this specific credential instance
             type: ["VerifiableCredential", "OpenBadgeCredential", "BoostCredential", "AchievementCredential"], // Ensure "Achievement" is in your contract's write.credentials.categories

docs/how-to-guides/deploy-infrastructure/connect-to-independent-network.md

@@ -466,7 +466,7 @@ const meritBadgeBoost = {
     "@context": [
       "https://www.w3.org/2018/credentials/v1",
       "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.1.json",
-      "https://ctx.learncard.com/boosts/1.0.0.json"
+      "https://ctx.learncard.com/boosts/1.0.3.json"
     ],
     "attachments": [],
     "credentialSubject": {

docs/how-to-guides/deploy-infrastructure/the-simplest-plugin.md

@@ -62,26 +62,26 @@ cd simple-plugin
 If you'd like to publish your plugin to npm for others to use, please see our documentation on [publishing plugins](the-simplest-plugin.md#publish-your-plugin-to-npm)
 {% endhint %}
 
-### Install @learncard/core
+### Install Dependencies
 
-Using your preferred package manager, install `@learncard/core`
+Using your preferred package manager, install `@learncard/core` (for the `Plugin` type) and `@learncard/init` (for initializing LearnCard):
 
 {% tabs %}
 {% tab title="pnpm" %}
 ```bash
-pnpm i @learncard/core
+pnpm i @learncard/core @learncard/init
 ```
 {% endtab %}
 
 {% tab title="yarn" %}
 ```bash
-yarn add @learncard/core
+yarn add @learncard/core @learncard/init
 ```
 {% endtab %}
 
 {% tab title="npm" %}
 ```bash
-npm i @learncard/core
+npm i @learncard/core @learncard/init
 ```
 {% endtab %}
 {% endtabs %}
@@ -145,7 +145,7 @@ Then, write your test:
 
 {% code title="test/index.test.ts" lineNumbers="true" %}
 ```typescript
-import { initLearnCard } from '@learncard/core';
+import { initLearnCard } from '@learncard/init';
 import { MyPlugin } from '../src/index';
 
 describe('MyPlugin', () => {
@@ -170,10 +170,12 @@ If all looks good, you should be able to `pnpm test` and successfully pass the t
 Now you can add it to a LearnCard object:
 
 ```typescript
+import { initLearnCard } from '@learncard/init';
+
 const learnCard = await initLearnCard();
 const learnCardWithMyPlugin = await learnCard.addPlugin(MyPlugin);
 
-console.log(learnCard.invoke.getFavoriteNumber()); // 4
+console.log(learnCardWithMyPlugin.invoke.getFavoriteNumber()); // 4
 ```
 
 ### Publish Your Plugin to NPM

docs/how-to-guides/implement-flows/claim-data-after-guardian-consent.md

@@ -50,7 +50,7 @@ const credential {
   "@context": [
     "https://www.w3.org/2018/credentials/v1",
     "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.1.json",
-    "https://ctx.learncard.com/boosts/1.0.0.json",
+    "https://ctx.learncard.com/boosts/1.0.3.json",
     {
       "tabby": "https://docs.mylittletabbycat.com/definitions#",
       "xsd": "https://www.w3.org/2001/XMLSchema#",

docs/introduction/ecosystem-architecture.md

@@ -14,7 +14,7 @@ Use this guide to understand how each part connects—from low-level credential
 
 Choose your stack:
 
-* `@learncard/core` SDK for programmatic control
+* `@learncard/init` SDK for programmatic control
 * LearnCloud Network API for backend integrations
 * LearnCloud Storage API for encrypted storage
 * LearnCloud AI API for AI-enabled credential flows

docs/quick-start/setup-and-prerequisites.md

@@ -104,17 +104,13 @@ This installs the essential module to initialize LearnCard
 
 #### LearnCard CLI (Optional)
 
-If you want to script or automate wallet actions via terminal:
+If you want to interactively explore wallet actions via terminal:
 
 ```bash
-npm install -g @learncard/cli
+npx @learncard/cli
 ```
 
-**🔎 Verify:**
-
-```bash
-learncard --version
-```
+This launches an interactive REPL where you can issue credentials, verify them, and explore the SDK.
 
 → See [CLI Documentation](../sdks/learncard-cli.md)
 
@@ -151,8 +147,8 @@ npm -v
 # Verify Git
 git --version
 
-# (Optional) Verify CLI
-learncard --version
+# (Optional) Launch CLI
+npx @learncard/cli
 ```
 
 Need help? Visit our [Troubleshooting Guide ](../sdks/learncard-core/troubleshooting-guide.md)or join the Community for support.

docs/quick-start/your-first-integration.md

@@ -47,7 +47,7 @@ This script:
 
 ## ✅ Prerequisites
 
-* Node.js (v14+)
+* Node.js (v18+)
 * A secure seed phrase (stored in `SECURE_SEED`)
 * A unique ID for your issuer (e.g. `my-awesome-org-profile`)