v2.0: rebuild as a portable AI memory wallet

Reposition CodeCart from a DSL note console to a copy-paste memory
wallet: card-based UI (preference / fact / status / boundary), a
round-trip protocol where the AI emits fenced codecart blocks that
merge back with supersede semantics, a first-run starter wizard,
honest token counting, light/dark themes, and offline-first storage
with file export, import and URL-hash transfer links (no account,
no server). Four languages (en, zh-CN, zh-TW, ja) with auto-detect
and manual switching; Chinese brand renamed to 思维卡. All docs
rewritten; DEVELOPER_API is now the open protocol spec. Legacy v1.3
localStorage data migrates automatically.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: AgentLex

.gitignore

@@ -0,0 +1,3 @@
+.DS_Store
+_private/
+.claude/

DEVELOPER_API.ja.md

@@ -1,81 +1,85 @@
-# CodeCart デベロッパー API ガイド (v1.3)
+# CodeCart プロトコル仕様 (v2.0)
 
 [English](DEVELOPER_API.md) | [简体中文](DEVELOPER_API.zh-CN.md) | [繁體中文](DEVELOPER_API.zh-TW.md) | **日本語**
 
 ## 目的
 
-このガイドは、ブラウザでの手動操作ではなく、APIコール、スクリプト、マルチエージェント（Multi-agent）フレームワーク、または CI/CD パイプラインを通じて CodeCart を利用する開発者や研究者を対象としています。
+本書は CodeCart の「ラウンドトリップ・プロトコル」を定義し、あらゆる AI 製品・エージェントフレームワーク・ブラウザー拡張・スクリプトがユーザーのメモリーウォレットを読み書きし、互換性を保てるようにするものです。プロトコルは意図的に極小です:普通のチャット返信の中で、どの LLM でも確実に出力できなければなりません。
 
-## コアアーキテクチャ
+## 3つの構成要素
 
-CodeCart v1.3 は、結晶化された外部メモリレイヤーとして機能します。そのアーキテクチャは、人間向けのインターフェースとマシンリーダーブルな状態を分離しています。
+1. **キャリーブロック**——ユーザーが AI に貼り付ける内容:有効なカード+モデルに更新の出力を求める指示。
+2. **`codecart` ブロック**——モデルが返信の最後に付けるメモリー更新(フェンス付きコードブロック)。
+3. **ウォレットファイル**——全カードを保持するエクスポート JSON。ユーザーが持ち運べる正準ストア。
 
-- **人間向け UI**: ポータブルな HTML ファイル（視覚化および手動調整用）。
-- **マシンメモリ**: エクスポートされた JSON カートリッジ（v1.3 形式）。
-- **プロンプトビルダー**: トークンコストを最小限に抑えるため、アクティブな（上書きされていない）ノードのみを抽出します。
-- **モデル契約**: LLM に対し、CodeCart DSL（`+CLAIM`, `>SUPERSEDE`, `+ANCHOR`）形式での出力を厳格に要求します。
+## 1. キャリーブロック
 
-## 標準的な API ワークフロー
+```
+[これは私の個人メモリーです(CodeCart ウォレット、<日付>)。すべての回答をこれに基づいてパーソナライズしてください。]
+- (preference) 短く、結論から答える
+- (fact) ネットショップを運営している
+- (boundary) 月1万円の予算を超える提案はしない
+---
+<codecart ブロックの追加をモデルに求める指示——正準の文言はアプリ内を参照>
+```
 
-### ステップ 1: カートリッジのエクスポート
-CodeCart UI の **詳細モード（Advanced Mode）** を使用して、現在のプロジェクト状態を JSON ファイルとしてエクスポートします。
+カードタイプ:`preference`(答え方の好み)、`fact`(安定した情報)、`status`(現在の関心事、変化する)、`boundary`(絶対ルール)。
+
+## 2. `codecart` ブロックの文法
+
+モデルは返信の最後にこう付けます:
+
+    ```codecart
+    + <type> | <内容>
+    ~ <古いメモリー行からそのまま引用した断片> => <修正後の内容>
+    - <退役させるメモリー行の断片>
+    ```
+
+- `+` はカード追加。`<type>` は4タイプのいずれか。省略時(`+ <内容>`)は `fact` として扱う——ただし誤検出を避けるためフェンス内のみ。
+- `~` は置き換え:テキストに `<断片>` を含む有効カードを(大文字小文字を無視して)探し、アーカイブして修正カードを追加。これがウォレットを肥大化させず最新に保つ仕組みです。
+- `-` は置き換えなしの退役(フェンス内のみ)。
+- 推奨モデルルール(キャリー指示に含まれます):最大5行;持続的な個人情報のみ;ユーザーの言語で書く;該当なしならブロック自体を省略。
+
+パーサーはフェンス外の行も受け付けてよいが、明示的な `<type> |` 接頭辞がある場合に限ります。
+
+## 3. ウォレットファイル (JSON)
+
+```json
+{
+  "version": 2,
+  "cards": [
+    {
+      "id": "m3k9x1ab2",
+      "type": "preference",
+      "text": "短く、結論から答える",
+      "status": "active",
+      "created": 1720300000000,
+      "updated": 1720300000000
+    }
+  ]
+}
+```
 
-### ステップ 2: コンパクトなコンテキストブロックの構築
-プロンプトに注入するために必要な情報のみを抽出します。以下のロジックにより、廃棄されたノードにトークンを浪費しないようにします。
+`status` は `active` か `archived`。コンシューマーは active カードのみを持ち込み、インポート時は `text` の重複(大文字小文字・前後空白を無視)をスキップしてマージしなければなりません。
 
-**Python 実装例:**
+## 参考:API パイプラインでウォレットを使う
 
 ```python
 import json
 
-# v1.3 でエクスポートされたカートリッジファイルを読み込む
-with open('codecart_export.json', 'r', encoding='utf-8') as f:
-    cart = json.load(f)
-
-active_nodes = []
-for n in cart.get('nodes', []):
-    # フィルタリング：すべてのアンカー（Anchor）と、アクティブな結論（Claim）のみを保持
-    if n.get('type') == 'anchor' or not n.get('isSuperseded'):
-        active_nodes.append(f"[{n['id']}] {n['content']}")
+with open("codecart-wallet.json", encoding="utf-8") as f:
+    wallet = json.load(f)
 
-context_block = "[CODECART CONTEXT]\n" + "\n".join(active_nodes)
-print(context_block)
-```
-
-### ステップ 3: モデル呼び出しへの注入
-LLM にコンテキストを処理させ、更新内容を厳格に DSL 形式で返却するように強制します。
-
-```python
-from openai import OpenAI
-
-client = OpenAI()
-
-system_prompt = (
-    "あなたは CodeCart メモリカートリッジへのアクセス権を持つアシスタントです。"
-    "分析後、安定した更新内容を CodeCart DSL のみを使用して要約してください。"
-    "新しいロジックには +CLAIM(id, '内容') を、更新には >SUPERSEDE(旧ID, 新ID, '理由') を使用してください。"
+carry = "\n".join(
+    f"- ({c['type']}) {c['text']}"
+    for c in wallet["cards"] if c["status"] == "active"
 )
-
-messages = [
-    {"role": "system", "content": f"{system_prompt}\n\n{context_block}"},
-    {"role": "user", "content": "現在のアーキテクチャをレビューし、スケーリング戦略を提案してください。"}
-]
-
-resp = client.chat.completions.create(
-    model="gpt-4o",
-    messages=messages
-)
-
-# モデルは生の DSL テキストを返します
-print(resp.choices[0].message.content)
+# carry を system prompt の先頭に付け、モデル出力中の
+# ```codecart``` ブロックを上記文法でパースしてマージする。
 ```
 
-### ステップ 4: マージ（反映）
-モデルが出力した DSL テキストを CodeCart の **詳細モード** コンソールに貼り付け、**⚡ 実行（EXECUTE）** をクリックして、視覚的なロジックツリーを更新します。
-
-## 効果的な API 利用のガイドライン
+## 互換性の約束
 
-1. **トークンの効率化**: 「デッド」ノード（置換済み/非アクティブ）をプロンプトに注入しないでください。
-2. **アンカーの安定性**: 変更不可のプロジェクトルールには `+ANCHOR` を使用し、「モデルのドリフト（脱線）」を防ぎます。
-3. **アトミックな結論**: LLM が1つの論理的結論に対して1つの独立したノードを生成するように調整してください。
-4. **自動スナップショット**: パイプラインの重要な意思決定ポイントで、スクリプトを使用して JSON スナップショットを自動保存することを推奨します。
+- ブロックタグは常にリテラル文字列 `codecart`。
+- 未知のカードタイプは `fact` として扱い、未知の JSON フィールドはラウンドトリップで保持すること。
+- v1.3 レガシーエクスポート(`nodes` + `+CLAIM`/`+ANCHOR` セマンティクス)の対応:`anchor → boundary`、`claim → fact`、`isSuperseded → archived`。

DEVELOPER_API.md

@@ -1,81 +1,85 @@
-# CodeCart Developer API Guide (v1.3)
+# CodeCart Protocol Specification (v2.0)
 
 **English** | [简体中文](DEVELOPER_API.zh-CN.md) | [繁體中文](DEVELOPER_API.zh-TW.md) | [日本語](DEVELOPER_API.ja.md)
 
 ## Purpose
 
-This guide is for developers and researchers who work through API calls, scripts, multi-agent frameworks, or CI/CD pipelines rather than manually copying text in a browser.
+This document specifies the CodeCart round-trip protocol so that any AI product, agent framework, browser extension or script can read, write and stay compatible with a user's memory wallet. The protocol is deliberately tiny: it must survive being emitted by any LLM inside a plain chat reply.
 
-## Core Architecture
+## The three artifacts
 
-CodeCart v1.3 functions as a crystallized external memory layer. The architecture separates the human interface from the machine-readable state:
+1. **Carry block** — what the user pastes *into* an AI chat: active cards + an instruction asking the model to emit updates.
+2. **`codecart` block** — what the model appends to its replies: memory updates in a fenced code block.
+3. **Wallet file** — the exported JSON that holds all cards; the user's canonical, portable store.
 
-- **Human-facing UI**: The portable HTML file.
-- **Machine memory**: The exported JSON cartridge (v1.3 format).
-- **Prompt builder**: Extracts only active (non-superseded) nodes to minimize token costs.
-- **Model contract**: The LLM is instructed to output strictly in CodeCart DSL (`+CLAIM`, `>SUPERSEDE`, `+ANCHOR`).
+## 1. Carry block
 
-## Standard API Workflow
+```
+[My personal memory — CodeCart wallet, <date>. Use it to personalize every answer.]
+- (preference) Answer concisely, conclusion first
+- (fact) I run a small online store
+- (boundary) Never suggest options over my $200/month budget
+---
+<instruction asking the model to append a codecart block — see the app for canonical wording>
+```
 
-### Step 1: Export the Cartridge
-Export your current project state as a JSON file using the **Advanced Mode** in the CodeCart UI.
+Card types: `preference` (how to answer), `fact` (stable info), `status` (current focus, expected to change), `boundary` (hard rule).
+
+## 2. `codecart` block grammar
+
+The model appends, at the end of a reply:
+
+    ```codecart
+    + <type> | <content>
+    ~ <fragment copied from an outdated memory line> => <corrected content>
+    - <fragment of a memory line to retire>
+    ```
+
+- `+` adds a card. `<type>` is one of the four types; if omitted (`+ <content>`), consumers should default to `fact` — but only inside a fenced block, to avoid false positives.
+- `~` supersedes: the consumer finds the active card whose text contains `<fragment>` (case-insensitive), archives it, and adds the corrected card. This is what keeps wallets current instead of ever-growing.
+- `-` retires a card without replacement (fenced block only).
+- Recommended model rules (already in the carry instruction): max 5 lines, only durable personal info, write contents in the user's language, omit the block when nothing qualifies.
+
+Parsers should accept the lines outside a fence too, but only when an explicit `<type> |` prefix is present.
+
+## 3. Wallet file (JSON)
+
+```json
+{
+  "version": 2,
+  "cards": [
+    {
+      "id": "m3k9x1ab2",
+      "type": "preference",
+      "text": "Answer concisely, conclusion first",
+      "status": "active",
+      "created": 1720300000000,
+      "updated": 1720300000000
+    }
+  ]
+}
+```
 
-### Step 2: Build a Compact Context Block
-Extract only relevant information to inject into your prompt. The following logic ensures you don't waste tokens on superseded nodes.
+`status` is `active` or `archived`. Consumers must carry only active cards, and must merge imports by skipping duplicate `text` values (case-insensitive, trimmed).
 
-**Python Example:**
+## Reference: consuming a wallet in an API pipeline
 
 ```python
 import json
 
-# Load v1.3 exported cartridge
-with open('codecart_export.json', 'r', encoding='utf-8') as f:
-    cart = json.load(f)
-
-active_nodes = []
-for n in cart.get('nodes', []):
-    # Filter: Keep all anchors and only active claims
-    if n.get('type') == 'anchor' or not n.get('isSuperseded'):
-        active_nodes.append(f"[{n['id']}] {n['content']}")
+with open("codecart-wallet.json", encoding="utf-8") as f:
+    wallet = json.load(f)
 
-context_block = "[CODECART CONTEXT]\n" + "\n".join(active_nodes)
-print(context_block)
-```
-
-### Step 3: Inject into Your Model Call
-Force the LLM to process the context and return updates strictly in DSL format.
-
-```python
-from openai import OpenAI
-
-client = OpenAI()
-
-system_prompt = (
-    "You are an assistant with access to a CodeCart memory cartridge. "
-    "After analysis, summarize stable updates using CodeCart DSL only. "
-    "Use +CLAIM(id, 'content') for new logic and >SUPERSEDE(old, new, 'why') for updates."
+carry = "\n".join(
+    f"- ({c['type']}) {c['text']}"
+    for c in wallet["cards"] if c["status"] == "active"
 )
-
-messages = [
-    {"role": "system", "content": f"{system_prompt}\n\n{context_block}"},
-    {"role": "user", "content": "Review the current architecture and propose a scaling strategy."}
-]
-
-resp = client.chat.completions.create(
-    model="gpt-4o",
-    messages=messages
-)
-
-# The model returns raw DSL
-print(resp.choices[0].message.content)
+# Prepend `carry` to your system prompt; parse ```codecart``` blocks
+# from model output with the grammar above and merge back.
 ```
 
-### Step 4: Merge Back
-Paste the model's DSL output back into the CodeCart **Advanced Mode** console and click **⚡ EXECUTE** to update your visual logic tree.
-
-## Rules for Good API Usage
+## Compatibility promises
 
-1. **Token Efficiency**: Never inject "dead" (superseded) nodes into the prompt.
-2. **Anchor Stability**: Use `+ANCHOR` for immutable project rules to prevent "model drift".
-3. **Atomic Claims**: Ensure the LLM generates one node per discrete logical conclusion.
-4. **Automated Snapshots**: Save JSON snapshots after major decision points in your pipeline.
+- The block tag is always the literal string `codecart`.
+- Unknown card types must be treated as `fact`, unknown JSON fields must be preserved on round-trip.
+- v1.3 legacy exports (`nodes` with `+CLAIM`/`+ANCHOR` semantics) map as: `anchor → boundary`, `claim → fact`, `isSuperseded → archived`.