release(0.3.0): framework-agnostic packages, Copilot provider, framework selector, CI fixes

faical-yannick-congo · claude · faical-yannick-congo · commit f04e1e8656e7 · 2026-03-24T10:44:37.000+01:00
Merges branch docs/framework-agnostic-packages

CI fixes:
- score-pr-knowledge.js: fix import path (src → dist), fix 4D-specific averaging
- build.mjs (cli + mcp-server): update esbuild aliases from @fluently/scorer to fluently-scorer

Package docs (scorer, cli, mcp-server): fully framework-agnostic framing — 4D is the
bundled default, any framework with named dimensions can be registered.

site/index.html:
- GitHub Copilot added as AI provider via GitHub Models API (OpenAI-compatible,
  github_pat_… token, models.inference.ai.azure.com)
- Framework selector dropdown in try-it demo — populated live from frameworks/index.json,
  filters knowledge entries to the selected framework
- Cycle text rendered generically from entry.dimensions keys (any framework)

site/frameworks.html:
- Expanded "Contribute a New Framework" section with Path A (manual PR, YAML template,
  local validation) and Path B (copy-paste agent prompt for Fluently MCP + GitHub MCP)

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/packages/cli/README.md b/packages/cli/README.md
@@ -1,8 +1,8 @@
 # fluently-cli
 
-**CLI for the [Fluently 4D Framework](https://fluently-org.github.io/fluently/) — score, compare, and contribute human-AI collaboration cycles from your terminal.**
+**Terminal CLI for [Fluently](https://fluently-org.github.io/fluently/) — score, compare, and contribute human-AI collaboration cycles across any registered framework.**
 
-Works with any AI agent: Claude, GPT-4o, Gemini, Mistral, GitHub Copilot, and more.
+Framework-agnostic. Bundles the AI Fluency 4D Framework as the default. Works with any AI agent: Claude, GPT-4o, Gemini, Mistral, GitHub Copilot, and more.
 
 [![npm version](https://img.shields.io/npm/v/fluently-cli.svg)](https://www.npmjs.com/package/fluently-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](../../LICENSE)
@@ -24,7 +24,7 @@ Requires Node.js 20+.
 
 | Command | What it does |
 |---------|-------------|
-| `fluent score <task>` | Find the 3 most similar 4D cycles to a task description |
+| `fluent score <task>` | Find the 3 most relevant cycles from the knowledge base for a task |
 | `fluent compare --description <desc> --delegation <intent>` | Match a task + delegation intent to the closest cycle |
 | `fluent list [domain]` | Browse all cycles, optionally filtered by domain |
 | `fluent contribute` | Interactive wizard to build and validate a new cycle as YAML |
@@ -78,7 +78,7 @@ Available domains: `coding` · `writing` · `research` · `education` · `legal`
 fluent contribute
 ```
 
-The interactive wizard walks through each of the 4 dimensions, validates the result against the Zod schema, and writes a `.yaml` file ready to commit and PR to the community repo.
+The interactive wizard walks through each dimension of the chosen framework, validates the result against the Zod schema, and writes a `.yaml` file ready to commit and PR to the community repo.
 
 ### Sync — stay up to date
 
@@ -90,9 +90,11 @@ Pulls the latest cycles from upstream. For a global npm install, use `npm update
 
 ---
 
-## The 4D Framework
+## Frameworks
 
-Every Fluently cycle covers four dimensions of human-AI collaboration:
+Fluently is framework-agnostic. Any collaboration framework with named dimensions can be registered. Each cycle carries a `framework_id` that determines which dimension fields it uses.
+
+The **AI Fluency 4D Framework** is bundled as the default:
 
 | Dimension | Question |
 |-----------|----------|
@@ -101,6 +103,8 @@ Every Fluently cycle covers four dimensions of human-AI collaboration:
 | 👁️ **Discernment** | How do you evaluate and trust the AI output? |
 | ✅ **Diligence** | What accountability steps follow AI involvement? |
 
+Additional frameworks can be added by contributing a YAML definition to `/frameworks/`. Cycles for that framework will be validated and scored against its own dimension schema automatically.
+
 Browse the full community knowledge base at **[fluently-org.github.io/fluently/knowledge.html](https://fluently-org.github.io/fluently/knowledge.html)**.
 
 ---
diff --git a/packages/cli/build.mjs b/packages/cli/build.mjs
@@ -37,8 +37,8 @@ await build({
     js: '#!/usr/bin/env node',
   },
   alias: {
-    '@fluently/scorer': resolve(root, 'packages/scorer/src/index.ts'),
-    '@fluently/scorer/schema': resolve(root, 'packages/scorer/src/schema.ts'),
+    'fluently-scorer': resolve(root, 'packages/scorer/src/index.ts'),
+    'fluently-scorer/schema': resolve(root, 'packages/scorer/src/schema.ts'),
   },
   external: ['esbuild'],
 });
diff --git a/packages/mcp-server/README.md b/packages/mcp-server/README.md
@@ -1,6 +1,8 @@
 # fluently-mcp-server
 
-**MCP server for the [Fluently 4D Framework](https://fluently-org.github.io/fluently/).** Exposes knowledge retrieval and contribution tools so any AI agent can find, reason over, and extend Fluently 4D cycles — without hardcoded scores.
+**MCP server for [Fluently](https://fluently-org.github.io/fluently/) — exposes knowledge retrieval and contribution tools so any AI agent can find, reason over, and extend collaboration cycles across any registered framework, without hardcoded scores.**
+
+Framework-agnostic. Bundles the AI Fluency 4D Framework as the default. Any framework with named dimensions can be registered.
 
 Works with Claude, GPT-4o, Gemini, Mistral, Llama, GitHub Copilot, Cursor, Cline, and any other MCP-compatible agent.
 
@@ -54,7 +56,7 @@ The same config block works for any MCP-compatible client. The server speaks std
 |------|---------|
 | `list_domains` | List available knowledge domains and cycle counts |
 | `find_relevant_cycles` | Retrieve ranked candidate cycles for a task — agent reasons, no false-precision scores |
-| `get_cycle_detail` | Full 4D cycle by ID (delegation · description · discernment · diligence) |
+| `get_cycle_detail` | Full cycle by ID — all dimension fields for its registered framework |
 | `get_dimension_guidance` | Antipatterns + examples for one dimension across all cycles |
 | `refresh_knowledge` | Re-fetch from the connector without restarting the server |
 | `contribute_cycle` | Validate a new cycle and submit it to the knowledge source |
diff --git a/packages/mcp-server/build.mjs b/packages/mcp-server/build.mjs
@@ -30,8 +30,8 @@ const shared = {
   target: 'node20',
   format: 'cjs',
   alias: {
-    '@fluently/scorer': resolve(root, 'packages/scorer/src/index.ts'),
-    '@fluently/scorer/schema': resolve(root, 'packages/scorer/src/schema.ts'),
+    'fluently-scorer': resolve(root, 'packages/scorer/src/index.ts'),
+    'fluently-scorer/schema': resolve(root, 'packages/scorer/src/schema.ts'),
   },
   external: ['esbuild'],
 };
diff --git a/packages/scorer/README.md b/packages/scorer/README.md
@@ -1,8 +1,10 @@
 # fluently-scorer
 
-**Shared scoring engine for the [Fluently 4D Framework](https://fluently-org.github.io/fluently/).** Validates knowledge YAML against the schema and ranks cycles by keyword similarity for any AI task.
+**Shared scoring and validation engine for human-AI collaboration frameworks.** Validates knowledge cycles against their framework schema, ranks them by similarity, and evaluates compliance. Framework-agnostic: works with any framework that defines named dimensions.
 
-Used internally by both `fluently-cli` and `fluently-mcp-server`. Expose it in your own tools to build on top of the Fluently knowledge base.
+Bundles the [AI Fluency 4D Framework](https://fluently-org.github.io/fluently/) as the default. Any framework registered in the knowledge base is automatically supported.
+
+Used internally by both `fluently-cli` and `fluently-mcp-server`. Import it directly to build on top of the Fluently knowledge base in your own tools.
 
 [![npm version](https://img.shields.io/npm/v/fluently-scorer.svg)](https://www.npmjs.com/package/fluently-scorer)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](../../LICENSE)
@@ -58,6 +60,7 @@ const results = scoreTask(input, './knowledge');
 results.forEach(({ entry, dimensionScores }) => {
     console.log(entry.title);
     console.log(dimensionScores);
+    // Dimension keys match the registered framework — e.g. for the 4D Framework:
     // { delegation: 80, description: 90, discernment: 70, diligence: 75 }
 });
 ```
diff --git a/packages/scorer/package.json b/packages/scorer/package.json
@@ -1,7 +1,7 @@
 {
   "name": "fluently-scorer",
   "version": "0.2.3",
-  "description": "Zero-dependency scoring engine for the Fluently 4D Framework. Validates YAML knowledge cycles with Zod and ranks them by keyword similarity — no API calls, no false-precision scores.",
+  "description": "Zero-dependency scoring and validation engine for human-AI collaboration frameworks. Validates knowledge cycles, ranks them by similarity, and evaluates framework compliance. Bundles the AI Fluency 4D Framework; any framework with named dimensions can be registered.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
diff --git a/scripts/score-pr-knowledge.js b/scripts/score-pr-knowledge.js
@@ -5,7 +5,7 @@ import path from 'path';
 import YAML from 'js-yaml';
 import { exec } from 'child_process';
 import { promisify } from 'util';
-import { scoreTask } from '../packages/scorer/src/engine.js';
+import { scoreTask } from '../packages/scorer/dist/engine.js';
 import { fileURLToPath } from 'url';
 
 const execAsync = promisify(exec);
@@ -50,14 +50,12 @@ async function scoreNewEntries() {
         KNOWLEDGE_DIR
       );
 
-      // Calculate overall score from top result's dimensionScores
+      // Calculate overall score from top result's dimensionScores (any framework)
       const topScores = result[0]?.dimensionScores || {};
-      const avgScore = (
-        (topScores.delegation || 0) +
-        (topScores.description || 0) +
-        (topScores.discernment || 0) +
-        (topScores.diligence || 0)
-      ) / 4;
+      const scoreValues = Object.values(topScores);
+      const avgScore = scoreValues.length
+        ? scoreValues.reduce((a, b) => a + b, 0) / scoreValues.length
+        : 0;
 
       scores.push(`- **${entry.title}** (${entry.domain}): ${avgScore.toFixed(1)}/100`);
     } catch (err) {
diff --git a/site/frameworks.html b/site/frameworks.html
@@ -204,41 +204,117 @@ <h2 class="text-2xl font-bold text-gray-900 mb-2">
          HOW TO CONTRIBUTE A FRAMEWORK
     ════════════════════════════════════════════════════════════════════════ -->
     <section class="max-w-4xl mx-auto px-4 sm:px-6 lg:px-8 py-12">
-        <h2 class="text-2xl font-bold text-gray-900 mb-6">
+        <h2 class="text-2xl font-bold text-gray-900 mb-2">
             <i class="fas fa-plus-circle text-green-600 mr-2"></i>Contribute a New Framework
         </h2>
-        <div class="grid sm:grid-cols-3 gap-6">
-            <div class="bg-white rounded-xl border border-gray-200 p-5">
-                <div class="text-2xl mb-2">📄</div>
-                <h3 class="font-bold text-gray-900 mb-1">1. Write a YAML file</h3>
-                <p class="text-sm text-gray-600">
-                    Create <code class="bg-gray-100 px-1 rounded text-xs">frameworks/your-framework.yaml</code>
-                    with <code class="bg-gray-100 px-1 rounded text-xs">id</code>,
-                    <code class="bg-gray-100 px-1 rounded text-xs">name</code>,
-                    <code class="bg-gray-100 px-1 rounded text-xs">dimensions</code>, and
-                    <code class="bg-gray-100 px-1 rounded text-xs">description</code>.
-                </p>
+        <p class="text-gray-600 text-sm mb-8">
+            Any collaboration framework with named dimensions can be registered. Two paths: submit a PR yourself, or ask your AI agent to build and test it for you.
+        </p>
+
+        <!-- Path A: Manual PR -->
+        <div class="mb-10">
+            <div class="flex items-center gap-2 mb-4">
+                <span class="bg-gray-900 text-white text-xs font-bold px-3 py-1 rounded-full">Path A</span>
+                <h3 class="text-lg font-bold text-gray-900">Manual PR</h3>
             </div>
-            <div class="bg-white rounded-xl border border-gray-200 p-5">
-                <div class="text-2xl mb-2">✅</div>
-                <h3 class="font-bold text-gray-900 mb-1">2. Validate &amp; index</h3>
-                <p class="text-sm text-gray-600">
-                    CI runs <code class="bg-gray-100 px-1 rounded text-xs">validate-frameworks.js</code>
-                    and regenerates <code class="bg-gray-100 px-1 rounded text-xs">frameworks/index.json</code>
-                    automatically on merge.
-                </p>
+            <div class="grid sm:grid-cols-3 gap-5">
+                <div class="bg-white rounded-xl border border-gray-200 p-5">
+                    <div class="text-2xl mb-2">📄</div>
+                    <h4 class="font-bold text-gray-900 mb-1">1. Write the YAML</h4>
+                    <p class="text-sm text-gray-600 mb-3">
+                        Fork the repo and create <code class="bg-gray-100 px-1 rounded text-xs">frameworks/your-id.yaml</code>.
+                        Required fields: <code class="bg-gray-100 px-1 rounded text-xs">id</code> (kebab-case),
+                        <code class="bg-gray-100 px-1 rounded text-xs">name</code>,
+                        <code class="bg-gray-100 px-1 rounded text-xs">version</code>,
+                        <code class="bg-gray-100 px-1 rounded text-xs">contributor</code>,
+                        <code class="bg-gray-100 px-1 rounded text-xs">description</code>,
+                        <code class="bg-gray-100 px-1 rounded text-xs">dimensions</code> (array with <code class="bg-gray-100 px-1 rounded text-xs">key</code>, <code class="bg-gray-100 px-1 rounded text-xs">label</code>, <code class="bg-gray-100 px-1 rounded text-xs">description</code>, <code class="bg-gray-100 px-1 rounded text-xs">canonical_order</code>).
+                    </p>
+                    <details class="text-xs">
+                        <summary class="font-bold text-indigo-600 cursor-pointer">Show template</summary>
+                        <pre class="bg-gray-50 border border-gray-200 rounded p-3 mt-2 overflow-x-auto text-gray-700 leading-relaxed">id: my-framework
+name: My Framework
+version: "1.0.0"
+contributor: Your Name
+description: >
+  One-paragraph description of the
+  framework and its goals.
+dimensions:
+  - key: plan
+    label: Plan
+    description: &gt;
+      What is decided before starting?
+    canonical_order: 1
+  - key: execute
+    label: Execute
+    description: &gt;
+      How is the work carried out?
+    canonical_order: 2
+  - key: review
+    label: Review
+    description: &gt;
+      How is the output evaluated?
+    canonical_order: 3</pre>
+                    </details>
+                </div>
+                <div class="bg-white rounded-xl border border-gray-200 p-5">
+                    <div class="text-2xl mb-2">🔍</div>
+                    <h4 class="font-bold text-gray-900 mb-1">2. Validate locally</h4>
+                    <p class="text-sm text-gray-600 mb-3">Run the validation script to catch errors before opening a PR:</p>
+                    <pre class="bg-gray-900 text-green-400 rounded p-3 text-xs overflow-x-auto">npm run build --workspace=packages/scorer
+node scripts/validate-frameworks.js</pre>
+                    <p class="text-xs text-gray-500 mt-2">CI reruns this automatically on every PR and rejects malformed definitions.</p>
+                </div>
+                <div class="bg-white rounded-xl border border-gray-200 p-5">
+                    <div class="text-2xl mb-2">🔗</div>
+                    <h4 class="font-bold text-gray-900 mb-1">3. Open a PR</h4>
+                    <p class="text-sm text-gray-600">Submit your PR. CI validates the schema, regenerates <code class="bg-gray-100 px-1 rounded text-xs">frameworks/index.json</code>, and the new framework appears in the knowledge base and this page after merge.</p>
+                    <div class="mt-3">
+                        <a href="https://github.com/Fluently-Org/fluently/compare"
+                           data-fluently="compare"
+                           target="_blank"
+                           class="inline-flex items-center gap-1 bg-gray-900 hover:bg-gray-700 text-white text-xs font-bold py-1.5 px-3 rounded transition">
+                            <i class="fab fa-github"></i> Open a PR
+                        </a>
+                    </div>
+                </div>
             </div>
-            <div class="bg-white rounded-xl border border-gray-200 p-5">
-                <div class="text-2xl mb-2">🔗</div>
-                <h3 class="font-bold text-gray-900 mb-1">3. Add knowledge cycles</h3>
-                <p class="text-sm text-gray-600">
-                    Knowledge YAML files tagged with your
-                    <code class="bg-gray-100 px-1 rounded text-xs">framework_id</code>
-                    will be validated against your framework's dimension keys.
-                </p>
+        </div>
+
+        <!-- Path B: Via Agent -->
+        <div class="mb-8">
+            <div class="flex items-center gap-2 mb-4">
+                <span class="bg-indigo-600 text-white text-xs font-bold px-3 py-1 rounded-full">Path B</span>
+                <h3 class="text-lg font-bold text-gray-900">Via your AI Agent</h3>
+            </div>
+            <p class="text-sm text-gray-600 mb-4">
+                If you have the Fluently MCP server connected, you can ask your agent to generate a framework YAML, validate it, and open the PR — all in one conversation.
+                Copy the prompt below and paste it to Claude, Copilot, Cursor, or any MCP-capable agent.
+            </p>
+            <div class="bg-gray-900 rounded-xl border border-gray-700 overflow-hidden">
+                <div class="flex items-center justify-between px-4 py-2 border-b border-gray-700">
+                    <span class="text-xs text-gray-400 font-mono">Agent prompt — paste as-is</span>
+                    <button onclick="copyAgentPrompt()" class="text-xs text-indigo-400 hover:text-indigo-300 font-bold transition">
+                        <i class="fas fa-copy mr-1"></i>Copy
+                    </button>
+                </div>
+                <pre id="agentPromptBlock" class="text-green-300 text-xs leading-relaxed px-4 py-4 overflow-x-auto whitespace-pre-wrap">I want to contribute a new collaboration framework to the Fluently knowledge base.
+
+Framework concept: [DESCRIBE YOUR FRAMEWORK HERE — e.g. "a 3-step Research framework: Question, Investigate, Synthesise"]
+
+Please:
+1. Use the `get_framework_detail` tool to inspect the existing 4D framework structure as a reference.
+2. Generate a valid `frameworks/[id].yaml` file following the same schema (id must be kebab-case, each dimension needs key, label, description, canonical_order).
+3. Run `node scripts/validate-frameworks.js` locally to confirm the file is valid.
+4. Confirm the YAML is ready to commit and provide the exact file contents.
+5. If I approve, create a branch named `feat/framework-[id]`, commit the YAML, and open a GitHub PR with a short description of the framework and its intended use cases.
+
+Do not open the PR without my explicit approval.</pre>
             </div>
+            <p class="text-xs text-gray-500 mt-2">Requires: Fluently MCP server connected + a GitHub MCP server or a PAT in your agent's settings.</p>
         </div>
-        <div class="mt-6 text-center">
+
+        <div class="mt-4 text-center">
             <a href="https://github.com/Fluently-Org/fluently/blob/main/CONTRIBUTING.md"
                data-fluently="contributing"
                target="_blank"
@@ -248,6 +324,18 @@ <h3 class="font-bold text-gray-900 mb-1">3. Add knowledge cycles</h3>
         </div>
     </section>
 
+    <script>
+    function copyAgentPrompt() {
+        const el = document.getElementById('agentPromptBlock');
+        navigator.clipboard.writeText(el.textContent.trim()).then(() => {
+            const btn = event.currentTarget;
+            btn.innerHTML = '<i class="fas fa-check mr-1"></i>Copied!';
+            btn.style.color = '#34d399';
+            setTimeout(() => { btn.innerHTML = '<i class="fas fa-copy mr-1"></i>Copy'; btn.style.color = ''; }, 2000);
+        });
+    }
+    </script>
+
     <!-- ═══════════════════════════════════════════════════════════════════════
          FOOTER
     ════════════════════════════════════════════════════════════════════════ -->
diff --git a/site/index.html b/site/index.html

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "fluently-scorer",`
`3`	`3`	`"version": "0.2.3",`
`4`		`- "description": "Zero-dependency scoring engine for the Fluently 4D Framework. Validates YAML knowledge cycles with Zod and ranks them by keyword similarity — no API calls, no false-precision scores.",`
	`4`	`+ "description": "Zero-dependency scoring and validation engine for human-AI collaboration frameworks. Validates knowledge cycles, ranks them by similarity, and evaluates framework compliance. Bundles the AI Fluency 4D Framework; any framework with named dimensions can be registered.",`
`5`	`5`	`"main": "dist/index.js",`
`6`	`6`	`"types": "dist/index.d.ts",`
`7`	`7`	`"exports": {`