Merge pull request #55 from JRS1986/feature/foam-knowledge-backend

Add Foam as a knowledge backend (MIT alternative to Obsidian)

Author: JRS1986

CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to CodingScaffold are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
 aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- **Foam knowledge backend.** `coding-scaffold knowledge create --backend foam` generates a
+  self-contained VS Code workspace under `.coding-scaffold/knowledge/` with an extensions
+  recommendation for `foam.foam-vscode`, Foam workspace settings, note templates under
+  `.foam/templates/`, and a `FOAM.md` entry note. Foam is MIT-licensed and runs entirely in
+  VS Code — a commercial-friendly alternative to Obsidian for organizations that don't want
+  the paid Obsidian Commercial license. See
+  [Knowledge Base / Foam](docs/wiki/Knowledge-Base.md#foam).
+
 ## [0.1.0] — 2026-05-18
 
 First tagged release. The scaffold is positioned for a controlled team pilot, not yet for

README.md

@@ -401,14 +401,26 @@ coding-scaffold knowledge create --target ~/dev/my-project --backend obsidian
 This creates Obsidian-friendly folders, backlinks, frontmatter templates, and `.obsidian/` settings
 while keeping Markdown as the source of truth.
 
+Foam mode (MIT-licensed VS Code extension, free for any use):
+
+```bash
+coding-scaffold knowledge create --target ~/dev/my-project --backend foam
+```
+
+Generates a self-contained VS Code workspace under `.coding-scaffold/knowledge/` with the Foam
+extension recommendation, workspace settings, and note templates. Use this when your organization
+needs a commercial-friendly alternative to Obsidian (Obsidian requires a paid Commercial license
+for organizations of more than two people).
+
 Optional MemPalace index:
 
 ```bash
 coding-scaffold knowledge create --target ~/dev/my-project --backend mempalace
 ```
 
-Use Obsidian when humans want better navigation and graph-style reading. Use MemPalace when the
-Markdown corpus grows large enough to benefit from semantic retrieval or MCP memory workflows.
+Use Obsidian or Foam when humans want better navigation and graph-style reading. Use MemPalace
+when the Markdown corpus grows large enough to benefit from semantic retrieval or MCP memory
+workflows.
 
 Hierarchical sharing is an optional organization pattern. Start with one repo and folder scopes when
 everyone has the same access. Use multiple Git remotes only when company, unit, department, or team
@@ -550,6 +562,7 @@ Optional commands can also generate:
 - `.coding-scaffold/ROUTELLM.md` and `routellm.config.yaml`.
 - `.coding-scaffold/OPEN_MULTI_AGENT.md`, `open-multi-agent.team.json`, and a TypeScript example.
 - Obsidian vault files under `.coding-scaffold/knowledge/.obsidian/`.
+- Foam workspace files under `.coding-scaffold/knowledge/.vscode/` and `.coding-scaffold/knowledge/.foam/`.
 - `.coding-scaffold/tools/caveman-compression/` and `.caveman.md` context sidecars.
 
 ## Commands

docs/wiki/Knowledge-Base.md

@@ -149,6 +149,38 @@ coding-scaffold knowledge create --target ~/dev/my-project --backend obsidian
 Use this when humans want a better reading and navigation layer. In WSL, install the desktop app on
 Windows and open `.coding-scaffold/knowledge` as a vault.
 
+Obsidian is free for personal use. Organizations of more than two people using Obsidian for
+business work need an Obsidian Commercial license (paid per user). If that's a blocker for your
+team, see the [Foam](#foam) section below — Foam is MIT-licensed and offers a similar workflow
+on top of VS Code.
+
+## Foam
+
+Foam mode is a free, MIT-licensed alternative to Obsidian. It runs as a VS Code extension and
+reads plain Markdown with `[[wikilink]]` syntax. The scaffold writes a self-contained VS Code
+workspace under `.coding-scaffold/knowledge/`:
+
+```bash
+coding-scaffold knowledge create --target ~/dev/my-project --backend foam
+```
+
+This generates:
+
+- `.vscode/extensions.json` — recommends `foam.foam-vscode` on first open.
+- `.vscode/settings.json` — Foam workspace defaults (graph view, daily-note directory, ignore
+  patterns for `.git/` and `_repo/`).
+- `.foam/templates/{decision,skill,agent}.md` — Foam note templates.
+- `FOAM.md` — entry note explaining the workflow.
+
+Open `.coding-scaffold/knowledge/` as a VS Code workspace and accept the extension recommendation
+to enable backlinks, the graph view, and template-based note creation. The scaffold's curated
+`wiki/` pages keep standard relative-link Markdown so they render on GitHub; use `[[wikilinks]]`
+in your own notes under `raw/`, `sessions/`, `decisions/`, and the layered scopes if you want
+Foam's graph view to connect them.
+
+Pick Foam over Obsidian when your organization needs commercial-friendly licensing or already
+standardizes on VS Code. Pick Obsidian when you want the dedicated desktop reading surface.
+
 ## MemPalace
 
 MemPalace mode adds notes for optional local semantic retrieval and MCP-compatible memory workflows:

src/coding_scaffold/cli.py

@@ -32,7 +32,7 @@
 CODING_TOOLS = ["opencode", "claude-code", "codex", "openclaude", "hermes", "pi", "both", "manual"]
 INSTALLABLE_TOOLS = ["opencode", "claude-code", "codex", "openclaude", "hermes", "pi", "both"]
 ADDONS = ["llmfit", "routellm", "open-multi-agent", "obsidian", "caveman-compression", "all"]
-KNOWLEDGE_BACKENDS = ["markdown", "obsidian", "mempalace"]
+KNOWLEDGE_BACKENDS = ["markdown", "obsidian", "foam", "mempalace"]
 KNOWLEDGE_BACKENDS_WITH_NONE = ["none", *KNOWLEDGE_BACKENDS]
 
 
@@ -95,7 +95,7 @@ def build_parser() -> argparse.ArgumentParser:
     init.add_argument("--install-addons", action="store_true", help="Install selected add-ons if missing.")
     init.add_argument(
         "--knowledge-backend",
-        choices=["none", "markdown", "obsidian", "mempalace"],
+        choices=["none", "markdown", "obsidian", "foam", "mempalace"],
         default=None,
         help="Configure shared knowledge during setup.",
     )
@@ -124,7 +124,7 @@ def build_parser() -> argparse.ArgumentParser:
     wizard.add_argument("--no-install-addons", action="store_true", help="Do not offer optional add-on setup.")
     wizard.add_argument(
         "--knowledge-backend",
-        choices=["none", "markdown", "obsidian", "mempalace"],
+        choices=["none", "markdown", "obsidian", "foam", "mempalace"],
         default=None,
         help="Configure shared knowledge during setup.",
     )
@@ -143,13 +143,13 @@ def build_parser() -> argparse.ArgumentParser:
 
     knowledge = sub.add_parser("knowledge", help="Create a shared team knowledge base.")
     knowledge.add_argument("--target", type=Path, default=Path.cwd(), help="Project directory.")
-    knowledge.add_argument("--backend", choices=["markdown", "obsidian", "mempalace"], default="markdown")
+    knowledge.add_argument("--backend", choices=["markdown", "obsidian", "foam", "mempalace"], default="markdown")
     knowledge.add_argument("--shared-remote", help="Optional GitHub/GitLab repo URL for team memory.")
     knowledge.add_argument("--adapter", choices=["none", "opencode"], default="opencode")
     knowledge_sub = knowledge.add_subparsers(dest="knowledge_action", metavar="action")
     knowledge_create = knowledge_sub.add_parser("create", help="Create or update shared team knowledge.")
     knowledge_create.add_argument("--target", type=Path, default=Path.cwd(), help="Project directory.")
-    knowledge_create.add_argument("--backend", choices=["markdown", "obsidian", "mempalace"], default="markdown")
+    knowledge_create.add_argument("--backend", choices=["markdown", "obsidian", "foam", "mempalace"], default="markdown")
     knowledge_create.add_argument("--shared-remote", help="Optional GitHub/GitLab repo URL for team memory.")
     knowledge_create.add_argument("--adapter", choices=["none", "opencode"], default="opencode")
     knowledge_status_canonical = knowledge_sub.add_parser("status", help="Report knowledge scope and maturity.")
@@ -243,7 +243,7 @@ def build_parser() -> argparse.ArgumentParser:
     setup_knowledge.add_argument("--target", type=Path, default=Path.cwd(), help="Project directory.")
     setup_knowledge.add_argument(
         "--backend",
-        choices=["markdown", "obsidian", "mempalace"],
+        choices=["markdown", "obsidian", "foam", "mempalace"],
         default="markdown",
         help="Knowledge backend to generate.",
     )
@@ -260,7 +260,7 @@ def build_parser() -> argparse.ArgumentParser:
     team_init.add_argument("--knowledge-remote", help="Shared knowledge Git remote for `team init`.")
     team_init.add_argument(
         "--knowledge-backend",
-        choices=["markdown", "obsidian", "mempalace"],
+        choices=["markdown", "obsidian", "foam", "mempalace"],
         default="markdown",
         help="Knowledge backend for `team init`.",
     )
@@ -897,9 +897,9 @@ def _maybe_setup_knowledge(
     shared_remote = getattr(args, "knowledge_remote", None)
     if is_wizard and sys.stdin.isatty() and backend is None:
         backend = _prompt_choice(
-            "Knowledge base backend (none/markdown/obsidian/mempalace)",
+            "Knowledge base backend (none/markdown/obsidian/foam/mempalace)",
             "markdown",
-            {"none", "markdown", "obsidian", "mempalace"},
+            {"none", "markdown", "obsidian", "foam", "mempalace"},
         )
         if backend != "none" and shared_remote is None:
             shared_remote = _prompt_optional(

src/coding_scaffold/knowledge.py

@@ -122,6 +122,8 @@ def write_knowledge_base(
     _collect(files, skipped, knowledge / "sync.md", _sync_template(shared_remote))
     if backend == "obsidian":
         _collect_obsidian_files(files, skipped, knowledge)
+    if backend == "foam":
+        _collect_foam_files(files, skipped, knowledge)
     if backend == "mempalace":
         _collect(files, skipped, knowledge / "mempalace.md", _mempalace_template())
     if adapter == "opencode":
@@ -344,6 +346,15 @@ def _knowledge_json(backend: str, shared_remote: str | None) -> str:
             "vault_path": ".coding-scaffold/knowledge",
             "open": "Open .coding-scaffold/knowledge as an Obsidian vault.",
         },
+        "foam": {
+            "optional": True,
+            "workspace_path": ".coding-scaffold/knowledge",
+            "extension": "foam.foam-vscode",
+            "open": (
+                "Open .coding-scaffold/knowledge as a VS Code workspace; "
+                "the Foam extension recommends itself on first open."
+            ),
+        },
     }
     return json.dumps(payload, indent=2, sort_keys=True) + "\n"
 
@@ -360,6 +371,15 @@ def _knowledge_guide(backend: str, shared_remote: str | None) -> str:
         if backend == "obsidian"
         else "Run `coding-scaffold knowledge --backend obsidian` later if you want an Obsidian vault."
     )
+    foam_line = (
+        "This scaffold also generated a VS Code workspace and Foam templates under "
+        "`.coding-scaffold/knowledge/`."
+        if backend == "foam"
+        else (
+            "Run `coding-scaffold knowledge --backend foam` later if you want a Foam workspace "
+            "(MIT-licensed VS Code extension)."
+        )
+    )
     return f"""# Team Knowledge Base
 
 The knowledge base is the shared memory for AI-enabled coding: decisions, project facts, useful
@@ -418,6 +438,15 @@ def _knowledge_guide(backend: str, shared_remote: str | None) -> str:
 Obsidian is useful when humans want backlinks, graph navigation, templates, and a pleasant reading
 surface. It still uses Markdown files, so Git remains the review and sharing mechanism.
 
+## Optional Foam
+
+{foam_line}
+
+Foam is a free, MIT-licensed VS Code extension that adds backlinks, a graph view, and templates on
+top of plain Markdown. Use it when teammates want Obsidian-style ergonomics without the commercial
+license (Obsidian is free for personal use but requires a paid Commercial license for
+organizations of more than two people).
+
 ## Optional MemPalace
 
 {mempalace_line}
@@ -972,3 +1001,147 @@ def _opencode_share_agent_pattern() -> str:
 context. Propose a small documented agent role or update an existing one. Include when to use it,
 what it may read or edit, verification expectations, and handoff rules.
 """
+
+
+def _collect_foam_files(files: list[Path], skipped: list[Path], knowledge: Path) -> None:
+    _collect(files, skipped, knowledge / "FOAM.md", _foam_start_here())
+    _collect(files, skipped, knowledge / ".vscode" / "extensions.json", _foam_extensions_json())
+    _collect(files, skipped, knowledge / ".vscode" / "settings.json", _foam_settings_json())
+    _collect(files, skipped, knowledge / ".foam" / "templates" / "decision.md", _foam_decision_template())
+    _collect(files, skipped, knowledge / ".foam" / "templates" / "skill.md", _foam_skill_template())
+    _collect(files, skipped, knowledge / ".foam" / "templates" / "agent.md", _foam_agent_template())
+
+
+def _foam_start_here() -> str:
+    return """# Foam Workspace
+
+This directory is also wired as a Foam workspace. Open `.coding-scaffold/knowledge/` in VS Code
+and accept the `foam.foam-vscode` recommendation to enable backlinks, the graph view, and the
+templates under `.foam/templates/`.
+
+Foam reads plain Markdown with `[[wikilink]]` syntax. The scaffold's curated wiki pages under
+`wiki/` use standard relative links so they render on GitHub; feel free to use `[[wikilinks]]` in
+your own notes under `raw/`, `sessions/`, `decisions/`, and the layered scopes.
+
+## Suggested workflow
+
+1. Capture raw notes from agent sessions in `raw/code-notes/` or `raw/incidents/`.
+2. Use Foam's graph view to spot recurring topics.
+3. Promote stable notes into `wiki/`, `decisions/`, or one of the hierarchical-sharing scopes
+   (`team/`, `department/`, `unit/`, `company/`) via pull request.
+4. Use the templates under `.foam/templates/` when starting a new decision, skill, or agent note
+   (right-click in VS Code → "Foam: Create new note from template").
+
+## Why Foam
+
+Foam is MIT-licensed and runs entirely in VS Code. It's a free alternative to Obsidian for teams
+that need a commercial license for organizational use. Markdown stays the source of truth — Git
+remains the review and sharing mechanism.
+"""
+
+
+def _foam_extensions_json() -> str:
+    return json.dumps(
+        {
+            "recommendations": [
+                "foam.foam-vscode",
+            ],
+        },
+        indent=2,
+        sort_keys=True,
+    ) + "\n"
+
+
+def _foam_settings_json() -> str:
+    return json.dumps(
+        {
+            "foam.edit.linkReferenceDefinitions": "off",
+            "foam.files.defaultExtension": ".md",
+            "foam.files.ignore": [
+                "**/.git/**",
+                "**/.coding-scaffold/**/_repo/**",
+            ],
+            "foam.graph.style": {
+                "background": "#202020",
+                "fontSize": 12,
+            },
+            "foam.openDailyNote.directory": "raw/meetings",
+        },
+        indent=2,
+        sort_keys=True,
+    ) + "\n"
+
+
+def _foam_decision_template() -> str:
+    return """---
+foam_template:
+  name: Decision
+  description: Architecture, model routing, tool choice, data handling, or workflow decision.
+---
+# Decision: $FOAM_TITLE
+
+Date: $FOAM_DATE_YEAR-$FOAM_DATE_MONTH-$FOAM_DATE_DATE
+Status: proposed | accepted | superseded
+
+Related: [[FOAM]]
+
+## Context
+
+What forced this decision?
+
+## Decision
+
+What did we decide?
+
+## Consequences
+
+What changes downstream? What did we trade off?
+
+## Agent Notes
+
+What should an AI coding agent know about this decision?
+"""
+
+
+def _foam_skill_template() -> str:
+    return """---
+foam_template:
+  name: Skill
+  description: A reusable prompt or workflow that the team has validated.
+---
+# Skill: $FOAM_TITLE
+
+Status: draft | validated | recommended | standard
+
+Related agents:
+
+## When To Use
+
+## Workflow
+
+## Verification
+
+## Maintenance Notes
+"""
+
+
+def _foam_agent_template() -> str:
+    return """---
+foam_template:
+  name: Agent
+  description: A trusted agent role with explicit scope and handoff rules.
+---
+# Agent: $FOAM_TITLE
+
+Status: draft | validated | recommended | standard
+
+Related skills:
+
+## Responsibility
+
+## Allowed Context
+
+## Write Scope
+
+## Handoff Rules
+"""