codex-arsenal 0.2.1 → 0.4.0

package/CODEX.md

@@ -6,6 +6,23 @@
 
 ---
 
+## Session Bootstrap
+
+When this repository is installed into a project, read `prompts/session-bootstrap.md` immediately after `CODEX.md` if it exists.
+
+If `configs/codex/session-config.json` exists, use it as the project-local source of truth for:
+
+- the session initializer path;
+- the code-style note path;
+- the meaningful-work criteria;
+- the Obsidian vault and inbox paths.
+
+If the configured code-style note exists, merge it into your working style before editing files.
+
+If the task satisfies the meaningful-work criteria, draft an Obsidian article at the end of the session.
+
+---
+
 ## 1. Think Before Coding
 
 **Don't assume. Don't hide confusion. Surface tradeoffs.**
@@ -91,7 +108,20 @@ Weak criteria ("make it work") require constant clarification.
 
 ---
 
-## 6. Context Awareness
+## 6. Token Budgeting
+
+**Spend context only where it changes the decision.**
+
+- Start with filenames, symbols, and short snippets before reading full files.
+- Prefer `rg` and targeted search over broad recursive reads.
+- Summarize long outputs immediately: key facts, file paths, line numbers, open questions.
+- Do not paste large logs back to the user. Quote only the failing line or smallest useful excerpt.
+- Reuse already-loaded context instead of re-reading the same files.
+- When handing off, compress to: goal, changed files, commands run, verification status, next risk.
+
+---
+
+## 7. Context Awareness
 
 **Codex has a limited context window — use it wisely.**
 
@@ -102,7 +132,7 @@ Weak criteria ("make it work") require constant clarification.
 
 ---
 
-## 7. Tool Use Discipline
+## 8. Tool Use Discipline
 
 **Every tool call has a cost. Make them count.**
 
@@ -118,4 +148,4 @@ Weak criteria ("make it work") require constant clarification.
 - Diffs contain fewer unnecessary changes
 - Fewer rewrites due to overcomplication
 - Clarifying questions come **before** implementation, not after mistakes
-- Agentic runs complete tasks end-to-end without silent failures or scope creep
+- Agentic runs complete tasks end-to-end without silent failures or scope creep

package/README.md

@@ -1,8 +1,8 @@
 # Codex-Arsenal
 
-Practical building blocks for working with OpenAI Codex, Claude Code, and other coding agents.
+Practical building blocks for working with OpenAI Codex.
 
-Codex-Arsenal is not an awesome list. It is a small, installable collection of agent guidelines, skills, prompts, workflows, configs, and plugin sketches that can be copied into real projects.
+Codex-Arsenal is not an awesome list. It is a small, installable collection of Codex guidelines, skills, prompts, workflows, configs, and plugin sketches that can be copied into real projects.
 
 ## Install
 
@@ -39,14 +39,19 @@ npm exec --yes --package=codex-arsenal -- codex-arsenal list
 ## CLI
 
 ```bash
-codex-arsenal init [--yes] [--dir <path>]
+codex-arsenal init [--yes] [--force] [--dir <path>]
 codex-arsenal list
-codex-arsenal get <id...> [--dir <path>]
+codex-arsenal get <id...> [--force] [--dir <path>]
+codex-obsidian-bridge sync [--dir <path>] [--force]
+codex-obsidian-bridge draft --title <text> --summary <text> [options]
 ```
 
 - `init` opens a small selector. With `--yes`, it installs default items without prompting.
 - `list` prints all installable manifest entries grouped by category.
 - `get` installs one or more manifest entries by id.
+- Existing files are skipped by default. Add `--force` to overwrite them intentionally.
+- `codex-obsidian-bridge sync` mirrors the session bootstrap, code style, and meaningful-work notes into an Obsidian vault.
+- `codex-obsidian-bridge draft` writes an article draft into the configured Obsidian inbox when the meaningful-work threshold is met.
 
 The package is published on npm as [`codex-arsenal`](https://www.npmjs.com/package/codex-arsenal).
 
@@ -57,19 +62,22 @@ The package is published on npm as [`codex-arsenal`](https://www.npmjs.com/packa
 | ID | Installs | Purpose |
 | --- | --- | --- |
 | `codex-md` | `CODEX.md` | Project-local behavioral guardrails for Codex-style agents. |
-| `claude-md` | `CLAUDE.md` | Project-local behavioral guardrails for Claude Code. |
 
 ### Configs
 
 | ID | Installs | Purpose |
 | --- | --- | --- |
 | `config-codex` | `.codex/config.json` | Starter Codex config. |
+| `config-session-bootstrap` | `.codex/session-config.json` | Session bootstrap and Obsidian bridge settings. |
 | `config-vscode` | `.vscode/settings.json` | VS Code settings for agent-assisted development. |
 
 ### Prompts
 
 | ID | Installs | Purpose |
 | --- | --- | --- |
+| `prompt-session-bootstrap` | `prompts/session-bootstrap.md` | Session startup instructions for Codex. |
+| `prompt-code-style` | `prompts/code-style.md` | Obsidian-backed code style note template. |
+| `prompt-meaningful-work` | `prompts/meaningful-work.md` | Criteria and template for end-of-session articles. |
 | `prompt-solo-dev` | `prompts/system-prompts/solo-dev.md` | Solo developer system prompt template. |
 
 ### Skills
@@ -79,12 +87,43 @@ The package is published on npm as [`codex-arsenal`](https://www.npmjs.com/packa
 | `skill-debug-workflow` | `skills/debug-workflow/` | Reproduce, diagnose, test, and fix bugs systematically. |
 | `skill-test-gen` | `skills/test-gen/` | Generate focused tests from behavior notes and function signatures. |
 | `skill-publishing-npm-packages` | `skills/publishing-npm-packages/SKILL.md` | Prepare, troubleshoot, and automate npm releases with Trusted Publishing. |
+| `skill-obsidian-session-loop` | `skills/obsidian-session-loop/SKILL.md` | Session startup, Obsidian sync, and end-of-session article drafting. |
 
 ### Plugins
 
 | ID | Installs | Purpose |
 | --- | --- | --- |
 | `plugin-context-window-compressor` | `plugins/context-window-compressor/` | Plugin sketch for compressing long agent context into concise handoff notes. |
+| `plugin-obsidian-codex-bridge` | `plugins/obsidian-codex-bridge/` | Plugin sketch for syncing Codex notes and article drafts with Obsidian. |
+
+## Obsidian Bridge
+
+The bridge is designed around two repeatable actions:
+
+1. `sync` the session initializer and style notes into a vault so the notes stay close to where they are read.
+2. `draft` a session article when the configured meaningful-work criteria are met.
+
+The default config lives in `.codex/session-config.json` and can be customized per project. A minimal vault layout looks like this:
+
+```text
+Codex/
+  Session-Initializer.md
+  Code-Style.md
+  Meaningful-Work.md
+Inbox/
+  Codex/
+```
+
+Example commands:
+
+```bash
+codex-obsidian-bridge sync --dir .
+codex-obsidian-bridge open --dir . --file "Codex/Session-Initializer.md"
+codex-obsidian-bridge reveal --dir . --file "Inbox/Codex/2026-06-11-refined-session-bootstrap.md"
+codex-obsidian-bridge draft --dir . --title "Refined session bootstrap" --summary "Added an Obsidian bridge and session-level startup guidance." --changes "added bridge CLI, added note templates" --decisions "kept config file-based" --verification "npm test" --signals "new integration boundary, README update"
+```
+
+If you have an Obsidian CLI or local launcher, add `obsidian.launch.open` and `obsidian.launch.reveal` templates to `.codex/session-config.json`. The bridge will use those templates first and fall back to an `obsidian://` launch URI if no CLI template is configured.
 
 ### Workflows
 
@@ -100,7 +139,7 @@ codex-arsenal/
   lib/                  manifest, installer, and fetcher
   configs/              reusable editor and agent configs
   plugins/              plugin sketches
-  prompts/              system prompt templates
+  prompts/              system prompt templates and session notes
   skills/               reusable agent skills
   workflows/            repeatable agentic workflows
   references/           curated references and notes
@@ -153,6 +192,19 @@ git push --follow-tags
 
 The publish workflow runs on `v*` tags and publishes with OIDC, so it does not require a long-lived `NPM_TOKEN`.
 
+## Codex Plugin Distribution
+
+The npm package is the current public distribution channel. Codex plugin library publishing is separate from npm and currently does not expose a general public submission flow in the public docs.
+
+For now, use one of these paths:
+
+- publish reusable files through `codex-arsenal` on npm;
+- keep plugin sketches under `plugins/`;
+- create a local or team marketplace file at `.agents/plugins/marketplace.json` when you want Codex app users to install a repo plugin from a local marketplace;
+- track OpenAI's Codex plugin documentation for an official public marketplace submission path.
+
+See `docs/codex-plugin-distribution.md` for the current assessment.
+
 ## Contribution Guidelines
 
 Good additions should be:

package/bin/cli.js

@@ -6,9 +6,11 @@ function printHelp() {
   console.log(`codex-arsenal
 
 Usage:
-  codex-arsenal init [--yes] [--dir <path>]
+  codex-arsenal init [--yes] [--force] [--dir <path>]
   codex-arsenal list
-  codex-arsenal get <id...> [--dir <path>]
+  codex-arsenal get <id...> [--force] [--dir <path>]
+
+By default, existing files are skipped. Use --force to overwrite them.
 `);
 }
 
@@ -28,7 +30,7 @@ function nonOptionArgs(args) {
       index += 1;
       continue;
     }
-    if (arg === "--yes" || arg === "-y") {
+    if (arg === "--yes" || arg === "-y" || arg === "--force") {
       continue;
     }
     result.push(arg);
@@ -51,6 +53,7 @@ function printList() {
 async function main(argv) {
   const [command = "init", ...args] = argv;
   const dir = readOption(args, "--dir", readOption(args, "-d", process.cwd()));
+  const force = args.includes("--force");
 
   if (command === "help" || command === "--help" || command === "-h") {
     printHelp();
@@ -67,12 +70,12 @@ async function main(argv) {
     if (!ids.length) {
       throw new Error("get requires at least one item id");
     }
-    await runInit({ preSelected: findManifestItems(ids), skipPrompt: true, dir });
+    await runInit({ preSelected: findManifestItems(ids), skipPrompt: true, dir, force });
     return;
   }
 
   if (command === "init") {
-    await runInit({ yes: args.includes("--yes") || args.includes("-y"), dir });
+    await runInit({ yes: args.includes("--yes") || args.includes("-y"), dir, force });
     return;
   }
 

package/bin/obsidian-bridge.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+import {
+  openObsidianNote,
+  draftObsidianArticle,
+  loadSessionConfig,
+  syncObsidianNotes
+} from "../lib/obsidian-bridge.js";
+
+function printHelp() {
+  console.log(`codex-obsidian-bridge
+
+Usage:
+  codex-obsidian-bridge sync [--dir <path>] [--force]
+  codex-obsidian-bridge open [--dir <path>] [--file <path>]
+  codex-obsidian-bridge reveal [--dir <path>] [--file <path>]
+  codex-obsidian-bridge draft --title <text> --summary <text> [options]
+
+Options:
+  --dir <path>             Project root that contains .codex/session-config.json
+  --force                  Overwrite existing Obsidian notes
+  --file <path>            Vault-relative note path to open or reveal
+  --title <text>           Article title
+  --summary <text>         Short summary of why the work mattered
+  --changes <items>        Comma-separated list of change bullets
+  --decisions <items>      Comma-separated list of decision bullets
+  --verification <items>   Comma-separated list of verification bullets
+  --next-steps <items>     Comma-separated list of follow-up bullets
+  --signals <items>        Comma-separated list of meaningful-work signals
+  --integration-boundary   Force an article when a new integration is introduced
+`);
+}
+
+function readOption(args, name, fallback = undefined) {
+  const index = args.indexOf(name);
+  if (index === -1) {
+    return fallback;
+  }
+  return args[index + 1] || fallback;
+}
+
+function readListOption(args, name) {
+  const value = readOption(args, name, "");
+  if (!value) {
+    return [];
+  }
+  return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
+
+async function main(argv) {
+  const [command = "help", ...args] = argv;
+  const cwd = readOption(args, "--dir", process.cwd());
+  const force = args.includes("--force");
+
+  if (command === "help" || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+
+  const config = await loadSessionConfig(cwd);
+
+  if (command === "sync") {
+    const result = await syncObsidianNotes({ cwd, config, force });
+    for (const file of result.synced) {
+      console.log(`synced ${file}`);
+    }
+    for (const file of result.skipped) {
+      console.log(`skipped ${file} (already exists; use --force to overwrite)`);
+    }
+    console.log(`target vault: ${result.targetVault}`);
+    return;
+  }
+
+  if (command === "open" || command === "reveal") {
+    const result = await openObsidianNote({
+      cwd,
+      config,
+      filePath: readOption(args, "--file"),
+      mode: command
+    });
+
+    if (!result.launched) {
+      console.log("Obsidian is disabled for this project.");
+      return;
+    }
+
+    console.log(result.mode === "command" ? "launched configured Obsidian command" : `opened ${result.spec.uri}`);
+    return;
+  }
+
+  if (command === "draft") {
+    const result = await draftObsidianArticle({
+      cwd,
+      config,
+      title: readOption(args, "--title"),
+      summary: readOption(args, "--summary"),
+      changes: readListOption(args, "--changes"),
+      decisions: readListOption(args, "--decisions"),
+      verification: readListOption(args, "--verification"),
+      nextSteps: readListOption(args, "--next-steps"),
+      signals: readListOption(args, "--signals"),
+      integrationBoundary: args.includes("--integration-boundary"),
+      force
+    });
+
+    if (result.skipped) {
+      console.log("no article drafted");
+      return;
+    }
+
+    console.log(`drafted ${result.written}`);
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/configs/codex/session-config.json

@@ -0,0 +1,30 @@
+{
+  "sessionInitializer": "prompts/session-bootstrap.md",
+  "codeStyleNote": "prompts/code-style.md",
+  "meaningfulWorkNote": "prompts/meaningful-work.md",
+  "obsidian": {
+    "enabled": true,
+    "cliCommand": "obsidian",
+    "vaultPath": "~/Obsidian/Codex",
+    "inboxPath": "Inbox/Codex",
+    "launch": {
+      "open": null,
+      "reveal": null
+    },
+    "noteTargets": {
+      "sessionInitializer": "Codex/Session-Initializer.md",
+      "codeStyle": "Codex/Code-Style.md",
+      "meaningfulWork": "Codex/Meaningful-Work.md"
+    }
+  },
+  "articleRules": {
+    "highSignalTriggers": [
+      "new or changed installable content",
+      "behavioral change",
+      "external integration",
+      "substantive README or workflow update"
+    ],
+    "minimumSignalsForDraft": 2,
+    "requiresVerification": true
+  }
+}

package/docs/codex-plugin-distribution.md

@@ -0,0 +1,54 @@
+# Codex Plugin Distribution
+
+## Current Assessment
+
+As of May 23, 2026, the practical public distribution path for Codex-Arsenal is npm. OpenAI's public Codex material says Codex users can browse the plugins library and create plugins in the Codex app, but it does not document a general public submission process for third-party plugins.
+
+Relevant OpenAI pages:
+
+- [Plugins and skills](https://openai.com/academy/codex-plugins-and-skills/)
+- [Codex](https://openai.com/codex/)
+- [Using Codex with your ChatGPT plan](https://help.openai.com/en/articles/11369540/)
+
+## Recommended Path
+
+1. Keep publishing installable skills, prompts, configs, and workflow files through `codex-arsenal` on npm.
+2. Keep plugin ideas in `plugins/<name>/` until they become real Codex plugins.
+3. When a plugin is ready for Codex app testing, convert it to a Codex plugin structure with `.codex-plugin/plugin.json`.
+4. Add a repo-local marketplace entry in `.agents/plugins/marketplace.json` for team/local installation.
+5. If OpenAI opens a formal public marketplace submission path, package the plugin manifest, documentation, permission model, and test notes for review.
+
+## Repo Marketplace Shape
+
+Use this shape for local or team discovery:
+
+```json
+{
+  "name": "codex-arsenal",
+  "interface": {
+    "displayName": "Codex-Arsenal"
+  },
+  "plugins": [
+    {
+      "name": "context-window-compressor",
+      "source": {
+        "source": "local",
+        "path": "./plugins/context-window-compressor"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}
+```
+
+## Before Submitting Anywhere
+
+- Define exactly what external systems the plugin touches.
+- Keep permissions narrow and explain authentication.
+- Provide a small demo workflow and screenshots if the plugin has UI.
+- Include test notes for install, auth, failure states, and uninstall.
+- Avoid bundling broad arsenals into one plugin. Publish focused plugins that solve one job well.

package/docs/npm-publishing.md

@@ -0,0 +1,35 @@
+# npm Publishing
+
+This package is set up for npm Trusted Publishing from GitHub Actions.
+
+## One-time npm setup
+
+1. Create or claim the `codex-arsenal` package on npm.
+2. On npmjs.com, open the package settings and add a Trusted Publisher:
+   - Provider: GitHub Actions
+   - Owner: `citron03`
+   - Repository: `Codex-Arsenal`
+   - Workflow filename: `publish.yml`
+   - Environment: `npm`
+3. After the first trusted publish works, set publishing access to require 2FA and disallow tokens.
+
+## Release process
+
+1. Ensure `main` is green.
+2. Update the version:
+
+   ```bash
+   npm version patch
+   ```
+
+3. Push the commit and tag:
+
+   ```bash
+   git push --follow-tags
+   ```
+
+GitHub Actions will run tests, perform a package dry run, and publish to npm from the `v*` tag.
+
+## Why Trusted Publishing
+
+Trusted Publishing uses short-lived OIDC credentials from GitHub Actions instead of a long-lived `NPM_TOKEN`. For public packages published from public repositories, npm also creates provenance attestations automatically.

package/lib/installer.js

@@ -2,12 +2,15 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { BASE_URL, MANIFEST } from "./manifest.js";
 import { fetchFile } from "./fetcher.js";
 
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
 async function readSourceFile(src) {
   try {
-    return await readFile(src, "utf8");
+    return await readFile(path.join(PACKAGE_ROOT, src), "utf8");
   } catch (error) {
     if (error.code !== "ENOENT") {
       throw error;
@@ -21,13 +24,27 @@ export async function installItems(items, targetDir, opts = {}) {
   let installed = 0;
   let failed = 0;
   const successes = [];
+  const skipped = [];
   const failures = [];
   const readSource = opts.readSourceFile || readSourceFile;
+  const force = !!opts.force;
 
   for (const item of items) {
     for (const file of item.files) {
       const destination = path.join(resolvedTarget, file.dest);
       try {
+        if (!force) {
+          try {
+            await readFile(destination, "utf8");
+            skipped.push(file.dest);
+            continue;
+          } catch (error) {
+            if (error.code !== "ENOENT") {
+              throw error;
+            }
+          }
+        }
+
         const content = await readSource(file.src);
         await mkdir(path.dirname(destination), { recursive: true });
         await writeFile(destination, content, "utf8");
@@ -40,7 +57,7 @@ export async function installItems(items, targetDir, opts = {}) {
     }
   }
 
-  return { installed, failed, successes, failures, targetDir: resolvedTarget };
+  return { installed, failed, successes, skipped, failures, targetDir: resolvedTarget };
 }
 
 function defaultItems() {
@@ -78,18 +95,24 @@ export async function runInit(opts = {}) {
 
   if (!selected.length) {
     console.log("No items selected.");
-    return { installed: 0, failed: 0, successes: [], failures: [], targetDir: path.resolve(opts.dir || ".") };
+    return { installed: 0, failed: 0, successes: [], skipped: [], failures: [], targetDir: path.resolve(opts.dir || ".") };
   }
 
   const result = await installItems(selected, opts.dir || process.cwd(), {
-    readSourceFile: opts.readSourceFile
+    readSourceFile: opts.readSourceFile,
+    force: opts.force
   });
   for (const file of result.successes) {
     console.log(`installed ${file}`);
   }
+  for (const file of result.skipped) {
+    console.log(`skipped ${file} (already exists; use --force to overwrite)`);
+  }
   for (const failure of result.failures) {
     console.log(`failed ${failure.dest} (${failure.error})`);
   }
-  console.log(`\nDone: ${result.installed} installed${result.failed ? `, ${result.failed} failed` : ""}.`);
+  console.log(
+    `\nDone: ${result.installed} installed${result.skipped.length ? `, ${result.skipped.length} skipped` : ""}${result.failed ? `, ${result.failed} failed` : ""}.`
+  );
   return result;
 }

package/lib/manifest.js

@@ -11,13 +11,6 @@ export const MANIFEST = [
     files: [{ src: "CODEX.md", dest: "CODEX.md" }],
     default: true
   },
-  {
-    id: "claude-md",
-    category: "Behavior Guidelines",
-    label: "CLAUDE.md",
-    description: "Behavior guidelines adapted for Claude Code agents.",
-    files: [{ src: "CLAUDE.md", dest: "CLAUDE.md" }]
-  },
   {
     id: "config-codex",
     category: "Configs",
@@ -25,6 +18,13 @@ export const MANIFEST = [
     description: "Starter Codex agent configuration.",
     files: [{ src: "configs/codex/config.json", dest: ".codex/config.json" }]
   },
+  {
+    id: "config-session-bootstrap",
+    category: "Configs",
+    label: ".codex/session-config.json",
+    description: "Session bootstrap and Obsidian bridge settings.",
+    files: [{ src: "configs/codex/session-config.json", dest: ".codex/session-config.json" }]
+  },
   {
     id: "config-vscode",
     category: "Configs",
@@ -32,6 +32,27 @@ export const MANIFEST = [
     description: "VS Code settings for AI-assisted development.",
     files: [{ src: "configs/vscode/settings.json", dest: ".vscode/settings.json" }]
   },
+  {
+    id: "prompt-session-bootstrap",
+    category: "Prompts",
+    label: "session-bootstrap",
+    description: "Session startup instructions for Codex.",
+    files: [{ src: "prompts/session-bootstrap.md", dest: "prompts/session-bootstrap.md" }]
+  },
+  {
+    id: "prompt-code-style",
+    category: "Prompts",
+    label: "code-style",
+    description: "Obsidian-backed code style note template.",
+    files: [{ src: "prompts/code-style.md", dest: "prompts/code-style.md" }]
+  },
+  {
+    id: "prompt-meaningful-work",
+    category: "Prompts",
+    label: "meaningful-work",
+    description: "Criteria and article template for meaningful Codex work.",
+    files: [{ src: "prompts/meaningful-work.md", dest: "prompts/meaningful-work.md" }]
+  },
   {
     id: "prompt-solo-dev",
     category: "Prompts",
@@ -69,6 +90,15 @@ export const MANIFEST = [
       { src: "skills/publishing-npm-packages/SKILL.md", dest: "skills/publishing-npm-packages/SKILL.md" }
     ]
   },
+  {
+    id: "skill-obsidian-session-loop",
+    category: "Skills",
+    label: "obsidian-session-loop",
+    description: "A Codex skill for session startup, Obsidian sync, and end-of-session article drafting.",
+    files: [
+      { src: "skills/obsidian-session-loop/SKILL.md", dest: "skills/obsidian-session-loop/SKILL.md" }
+    ]
+  },
   {
     id: "plugin-context-window-compressor",
     category: "Plugins",
@@ -79,6 +109,16 @@ export const MANIFEST = [
       { src: "plugins/context-window-compressor/plugin.json", dest: "plugins/context-window-compressor/plugin.json" }
     ]
   },
+  {
+    id: "plugin-obsidian-codex-bridge",
+    category: "Plugins",
+    label: "obsidian-codex-bridge",
+    description: "Plugin sketch for syncing Codex notes and article drafts with Obsidian.",
+    files: [
+      { src: "plugins/obsidian-codex-bridge/README.md", dest: "plugins/obsidian-codex-bridge/README.md" },
+      { src: "plugins/obsidian-codex-bridge/plugin.json", dest: "plugins/obsidian-codex-bridge/plugin.json" }
+    ]
+  },
   {
     id: "workflow-solo-dev-loop",
     category: "Workflows",

package/lib/obsidian-bridge.js

@@ -0,0 +1,354 @@
+import { execFile } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const execFileAsync = promisify(execFile);
+
+export function resolveConfigPath(cwd = process.cwd()) {
+  return path.join(cwd, ".codex", "session-config.json");
+}
+
+export function resolvePackageAsset(...segments) {
+  return path.join(PACKAGE_ROOT, ...segments);
+}
+
+export function defaultNoteTargets() {
+  return {
+    sessionInitializer: "Codex/Session-Initializer.md",
+    codeStyle: "Codex/Code-Style.md",
+    meaningfulWork: "Codex/Meaningful-Work.md"
+  };
+}
+
+export function defaultLaunchTemplates() {
+  return {
+    open: null,
+    reveal: null
+  };
+}
+
+export function normalizeVaultPath(vaultPath, cwd = process.cwd()) {
+  if (!vaultPath) {
+    return null;
+  }
+  if (vaultPath.startsWith("~")) {
+    const homeDir = process.env.HOME || process.env.USERPROFILE || "";
+    return path.resolve(homeDir, vaultPath.slice(1).replace(/^\//, ""));
+  }
+  return path.resolve(cwd, vaultPath);
+}
+
+export function getVaultName(vaultPath) {
+  return path.basename(vaultPath);
+}
+
+export function slugifyTitle(title) {
+  return title
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 72) || "session-note";
+}
+
+export function isoDateInSeoul(date = new Date()) {
+  return new Intl.DateTimeFormat("en-CA", {
+    timeZone: "Asia/Seoul",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit"
+  }).format(date);
+}
+
+export async function readJsonFile(filePath) {
+  const raw = await readFile(filePath, "utf8");
+  return JSON.parse(raw);
+}
+
+function normalizeTemplateValue(value, context) {
+  if (typeof value === "string") {
+    return value
+      .replaceAll("{vault}", context.vaultName)
+      .replaceAll("{vaultPath}", context.vaultRoot)
+      .replaceAll("{file}", context.filePath)
+      .replaceAll("{mode}", context.mode);
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeTemplateValue(item, context));
+  }
+
+  return value;
+}
+
+export function resolveObsidianLaunchSpec({
+  cwd = process.cwd(),
+  config,
+  filePath,
+  mode = "open"
+} = {}) {
+  const resolvedConfig = config || {};
+  const obsidian = resolvedConfig.obsidian || {};
+  if (!obsidian.enabled) {
+    return { type: "disabled" };
+  }
+
+  const vaultRoot = normalizeVaultPath(obsidian.vaultPath, cwd);
+  const vaultName = getVaultName(vaultRoot);
+  const notePath = filePath || obsidian.noteTargets?.sessionInitializer || defaultNoteTargets().sessionInitializer;
+  const absoluteNotePath = path.isAbsolute(notePath) ? notePath : path.join(vaultRoot, notePath);
+  const relativeFilePath = path.relative(vaultRoot, absoluteNotePath);
+
+  if (relativeFilePath.startsWith("..")) {
+    throw new Error(`Obsidian note must be inside the vault: ${notePath}`);
+  }
+
+  const templates = {
+    ...defaultLaunchTemplates(),
+    ...(obsidian.launch || {})
+  };
+  const template = templates[mode];
+
+  if (template) {
+    return {
+      type: "command",
+      command: template.command || obsidian.cliCommand || "obsidian",
+      args: normalizeTemplateValue(template.args || [], {
+        vaultName,
+        vaultRoot,
+        filePath: relativeFilePath,
+        mode
+      }),
+      cwd: vaultRoot
+    };
+  }
+
+  return {
+    type: "uri",
+    uri: `obsidian://open?vault=${encodeURIComponent(vaultName)}&file=${encodeURIComponent(relativeFilePath)}`
+  };
+}
+
+export async function launchObsidianTarget(spec, runner = execFileAsync) {
+  if (spec.type === "disabled") {
+    return { launched: false, mode: "disabled" };
+  }
+
+  if (spec.type === "command") {
+    await runner(spec.command, spec.args, { cwd: spec.cwd });
+    return { launched: true, mode: "command" };
+  }
+
+  if (spec.type === "uri") {
+    if (process.platform === "darwin") {
+      await runner("open", [spec.uri]);
+    } else if (process.platform === "linux") {
+      await runner("xdg-open", [spec.uri]);
+    } else if (process.platform === "win32") {
+      await runner("cmd", ["/c", "start", "", spec.uri]);
+    } else {
+      throw new Error(`Unsupported platform for launching Obsidian: ${process.platform}`);
+    }
+    return { launched: true, mode: "uri" };
+  }
+
+  throw new Error(`Unknown Obsidian launch spec type: ${spec.type}`);
+}
+
+export async function loadSessionConfig(cwd = process.cwd(), readJson = readJsonFile) {
+  const projectConfigPath = resolveConfigPath(cwd);
+
+  try {
+    return await readJson(projectConfigPath);
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+
+  const packageConfigPath = resolvePackageAsset("configs", "codex", "session-config.json");
+  return readJson(packageConfigPath);
+}
+
+export function shouldDraftArticle({ signals = [], config, integrationBoundary = false }) {
+  if (integrationBoundary) {
+    return true;
+  }
+
+  const minimumSignals = config?.articleRules?.minimumSignalsForDraft ?? 2;
+  return signals.length >= minimumSignals;
+}
+
+export function buildArticleMarkdown({
+  title,
+  summary,
+  changes = [],
+  decisions = [],
+  verification = [],
+  nextSteps = [],
+  signals = []
+}) {
+  const sections = [
+    `# ${title}`,
+    "",
+    `- Date: ${isoDateInSeoul()}`,
+    signals.length ? `- Signals: ${signals.join(", ")}` : null,
+    "",
+    "## Why It Mattered",
+    summary || "TBD",
+    "",
+    "## What Changed",
+    ...(changes.length ? changes.map((change) => `- ${change}`) : ["- TBD"]),
+    "",
+    "## Decisions",
+    ...(decisions.length ? decisions.map((decision) => `- ${decision}`) : ["- TBD"]),
+    "",
+    "## Verification",
+    ...(verification.length ? verification.map((item) => `- ${item}`) : ["- TBD"]),
+    "",
+    "## Next Steps",
+    ...(nextSteps.length ? nextSteps.map((step) => `- ${step}`) : ["- TBD"])
+  ];
+
+  return sections.filter((line) => line !== null).join("\n");
+}
+
+async function readSourceMarkdown(relativePath, cwd = process.cwd()) {
+  if (path.isAbsolute(relativePath)) {
+    return readFile(relativePath, "utf8");
+  }
+
+  const localPath = path.resolve(cwd, relativePath);
+  try {
+    return await readFile(localPath, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+
+  return readFile(resolvePackageAsset(relativePath), "utf8");
+}
+
+async function ensureDirectoryFor(filePath) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+}
+
+async function writeIfNeeded(destination, content, force) {
+  if (!force) {
+    try {
+      await readFile(destination, "utf8");
+      return "skipped";
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+    }
+  }
+
+  await ensureDirectoryFor(destination);
+  await writeFile(destination, content, "utf8");
+  return "written";
+}
+
+export async function syncObsidianNotes({ cwd = process.cwd(), config, force = false, readSource = readSourceMarkdown } = {}) {
+  const resolvedConfig = config || (await loadSessionConfig(cwd));
+  const obsidian = resolvedConfig.obsidian || {};
+  if (!obsidian.enabled) {
+    return { synced: [], skipped: [], targetVault: null };
+  }
+
+  const vaultRoot = normalizeVaultPath(obsidian.vaultPath, cwd);
+  const targets = {
+    ...defaultNoteTargets(),
+    ...(obsidian.noteTargets || {})
+  };
+
+  const notes = [
+    {
+      src: resolvedConfig.sessionInitializer || "prompts/session-bootstrap.md",
+      dest: targets.sessionInitializer
+    },
+    {
+      src: resolvedConfig.codeStyleNote || "prompts/code-style.md",
+      dest: targets.codeStyle
+    },
+    {
+      src: resolvedConfig.meaningfulWorkNote || "prompts/meaningful-work.md",
+      dest: targets.meaningfulWork
+    }
+  ];
+
+  const synced = [];
+  const skipped = [];
+
+  for (const note of notes) {
+    const sourceContent = await readSource(note.src, cwd);
+    const destination = path.join(vaultRoot, note.dest);
+    const status = await writeIfNeeded(destination, sourceContent, force);
+    if (status === "written") {
+      synced.push(note.dest);
+    } else {
+      skipped.push(note.dest);
+    }
+  }
+
+  return { synced, skipped, targetVault: vaultRoot };
+}
+
+export async function draftObsidianArticle({
+  cwd = process.cwd(),
+  config,
+  title,
+  summary,
+  changes = [],
+  decisions = [],
+  verification = [],
+  nextSteps = [],
+  signals = [],
+  integrationBoundary = false,
+  force = false
+} = {}) {
+  const resolvedConfig = config || (await loadSessionConfig(cwd));
+  const obsidian = resolvedConfig.obsidian || {};
+  if (!obsidian.enabled) {
+    return { written: null, skipped: true, targetVault: null };
+  }
+
+  if (!shouldDraftArticle({ signals, config: resolvedConfig, integrationBoundary })) {
+    return { written: null, skipped: true, targetVault: normalizeVaultPath(obsidian.vaultPath, cwd) };
+  }
+
+  const vaultRoot = normalizeVaultPath(obsidian.vaultPath, cwd);
+  const inboxPath = obsidian.inboxPath || "Inbox/Codex";
+  const articleTitle = title || "Codex Session Article";
+  const fileName = `${isoDateInSeoul()}-${slugifyTitle(articleTitle)}.md`;
+  const destination = path.join(vaultRoot, inboxPath, fileName);
+  const content = buildArticleMarkdown({
+    title: articleTitle,
+    summary,
+    changes,
+    decisions,
+    verification,
+    nextSteps,
+    signals
+  });
+
+  const status = await writeIfNeeded(destination, content, force);
+  return { written: status === "written" ? path.relative(vaultRoot, destination) : null, skipped: status !== "written", targetVault: vaultRoot };
+}
+
+export async function openObsidianNote({
+  cwd = process.cwd(),
+  config,
+  filePath,
+  mode = "open",
+  runner
+} = {}) {
+  const spec = resolveObsidianLaunchSpec({ cwd, config, filePath, mode });
+  const result = await launchObsidianTarget(spec, runner);
+  return { ...result, spec };
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "codex-arsenal",
-  "version": "0.2.1",
-  "description": "A practical arsenal of Codex and Claude Code plugins, skills, prompts, workflows, and configs.",
+  "version": "0.4.0",
+  "description": "A practical arsenal of Codex plugins, skills, prompts, workflows, and configs.",
   "type": "module",
   "bin": {
-    "codex-arsenal": "bin/cli.js"
+    "codex-arsenal": "bin/cli.js",
+    "codex-obsidian-bridge": "bin/obsidian-bridge.js"
   },
   "scripts": {
     "test": "node --test"
@@ -22,9 +23,10 @@
   },
   "files": [
     "bin/",
+    "docs/codex-plugin-distribution.md",
+    "docs/npm-publishing.md",
     "lib/",
     "CODEX.md",
-    "CLAUDE.md",
     "configs/",
     "plugins/",
     "prompts/",
@@ -36,7 +38,6 @@
   },
   "keywords": [
     "codex",
-    "claude-code",
     "ai-agent",
     "developer-tools",
     "prompt-engineering"

package/plugins/obsidian-codex-bridge/README.md

@@ -0,0 +1,30 @@
+# obsidian-codex-bridge
+
+Plugin sketch for connecting Codex sessions to an Obsidian vault.
+
+## Goal
+
+Make the session bootstrap, code-style note, and end-of-session article draft part of one loop instead of separate manual steps.
+
+## Proposed Modes
+
+- `bootstrap`: read the configured session note and merge project settings.
+- `sync`: copy or mirror the latest code-style and session notes into the vault.
+- `draft-article`: write a session article into the Obsidian inbox when the meaningful-work criteria are met.
+
+## Suggested Settings
+
+- `configs/codex/session-config.json`
+- `prompts/session-bootstrap.md`
+- `prompts/code-style.md`
+- `prompts/meaningful-work.md`
+
+## Obsidian CLI
+
+If an `obsidian` command is available, the bridge can use it to open the vault, reveal the generated note, or hand off to a vault-local workflow. If the CLI is not available, keep the markdown files as the source of truth and mirror them manually.
+
+## Practical CLI
+
+The repository now ships a small `codex-obsidian-bridge` command that can sync the notes, open or reveal a note, and draft an article into the configured inbox.
+
+If a project has an Obsidian CLI, configure `obsidian.launch.open` and `obsidian.launch.reveal` in `.codex/session-config.json`. Otherwise the bridge falls back to an `obsidian://` URI launch.

package/plugins/obsidian-codex-bridge/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "obsidian-codex-bridge",
+  "version": "0.1.0",
+  "description": "Sketch for connecting Codex session notes and article drafts to Obsidian.",
+  "entry": "README.md"
+}

package/prompts/code-style.md

@@ -0,0 +1,21 @@
+# Code Style Note
+
+This note is meant to live in Obsidian and flow back into session startup.
+
+## Baseline Style
+
+- Prefer small, direct modules with one responsibility.
+- Keep names explicit and stable.
+- Favor readable control flow over clever abstractions.
+- Match the repository's existing style before introducing new patterns.
+- Keep comments rare and only use them when the intent would otherwise be hard to follow.
+
+## Example Source of Inspiration
+
+Use widely adopted linting conventions such as Airbnb-style JavaScript guidance as a reference point, but adapt the final rules to the current repository.
+
+## Project-Specific Overrides
+
+- Document any exceptions here before asking the agent to apply them.
+- If a project wants a different style for a specific directory, note that directory here.
+- Keep the note short enough that it can be read at the start of every session.

package/prompts/meaningful-work.md

@@ -0,0 +1,30 @@
+# Meaningful Work Criteria
+
+Use these criteria to decide when a Codex session should generate an Obsidian article at the end of the task.
+
+## Trigger Rules
+
+Draft an article when the session meets at least two of these signals:
+
+- the change touches two or more repository files in one coherent slice;
+- the task introduces or changes installable content, configs, or workflows;
+- the work changes behavior, not just copy or formatting;
+- the change requires verification beyond a quick smoke check;
+- the task includes a substantive README or documentation update.
+
+Always draft an article when the session introduces a new integration boundary, such as a bridge to Obsidian or another external tool.
+
+## Article Template
+
+Use this outline for the draft:
+
+1. Title
+2. Why the change mattered
+3. What changed
+4. Decisions and tradeoffs
+5. Verification performed
+6. What to revisit later
+
+## Writing Rule
+
+Keep the article concrete. Write about the decision, the structure, and the follow-up work, not just the file list.

package/prompts/session-bootstrap.md

@@ -0,0 +1,22 @@
+# Session Bootstrap
+
+Use this file as the first project-local note after `CODEX.md`.
+
+## Startup Order
+
+1. Read `configs/codex/session-config.json` if it exists.
+2. Load the configured session initializer, code style note, and meaningful-work note.
+3. Merge the current task with the project-specific style guidance.
+4. Check whether Obsidian integration is available before drafting session notes.
+5. If the bridge is available, sync the session notes before starting the task.
+
+## What This Session Needs
+
+- Keep a short, explicit summary of the current goal.
+- Keep the active assumptions visible.
+- Prefer the simplest change that still satisfies the task.
+- Treat the configured code-style note as the source of truth for formatting and tone.
+
+## End-of-Session Rule
+
+If the current work satisfies the meaningful-work criteria, create a draft article in the configured Obsidian inbox and summarize the result there.

package/skills/obsidian-session-loop/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: obsidian-session-loop
+description: Use when starting or ending a Codex session that should read project-local session notes, sync Obsidian-backed style guidance, and draft an article when the work is meaningful.
+---
+
+# Obsidian Session Loop
+
+## Overview
+
+Use this skill when a project keeps session guidance in `CODEX.md`, stores session settings in `.codex/session-config.json`, and mirrors the working notes into an Obsidian vault.
+
+## When To Use
+
+- At the start of a Codex session for this repository.
+- When the project wants a code-style note to influence the current session.
+- When the work should produce a session article in Obsidian.
+- When the task touches the session bootstrap, Obsidian bridge, or the meaningful-work criteria.
+
+## Session Startup
+
+1. Read `CODEX.md` first.
+2. Load `.codex/session-config.json` if it exists.
+3. Read the configured session initializer, code-style note, and meaningful-work note.
+4. Sync the notes into Obsidian if `codex-obsidian-bridge` is available.
+5. Merge the code-style note into the current working style before editing files.
+
+## Meaningful Work Check
+
+Treat the work as meaningful when at least two of these are true:
+
+- the change spans multiple files in one coherent slice;
+- the task adds or changes installable content, configs, or workflows;
+- the work changes behavior rather than only copy;
+- verification is required beyond a trivial smoke test;
+- the README or user-facing guidance needs a substantive update.
+
+Always treat new integration boundaries as meaningful, including the Obsidian bridge itself.
+
+## End Of Session
+
+1. Summarize the actual change, not the file list.
+2. If the meaningful-work check passes, draft an Obsidian article with the bridge CLI.
+3. Include what changed, why it mattered, the tradeoffs, verification, and follow-up work.
+
+## Guardrails
+
+- Keep the session bootstrap short and readable.
+- Prefer the configured note paths over hardcoded vault locations.
+- Do not draft an article for tiny formatting-only changes.
+- Do not overwrite a user’s Obsidian note unless `--force` was intentional.

package/CLAUDE.md

@@ -1,15 +0,0 @@
-# CLAUDE.md
-
-Use this file as a project-local behavior guide for Claude Code agents.
-
-## Operating Principles
-
-- Read the repository instructions before editing.
-- Keep changes small and directly tied to the task.
-- Prefer tests before behavior changes.
-- Explain uncertainty instead of guessing silently.
-- Do not overwrite user work unless explicitly asked.
-
-## Completion Criteria
-
-Before reporting completion, run the smallest command that proves the change works and summarize the result.