concept-atlas-dense-explain

Concept Atlas Dense Explain

すべてを concept-atlas-dense-explain CLI 経由で実行し、必ず npx を使用してください。必要なものはすべてこのファイルと同梱の references/ にあります。フレームワークリポジトリやインストール済みパッケージのファイルを読んだり、スキルディレクトリから実装ファイルをコピーしたり、React/Vite アプリを再作成したりしないでください。コマンド名が不明な場合は、npx concept-atlas-dense-explain help を実行してください。ユーザーがファイルではなくプロンプト／方法論だけを求めている場合も、シェルを選んで有効な MDX を出力してください。CLI が必要なのは検証とコンパイルだけです。

CLI の実行

どのディレクトリからでも、必ず npx 経由で CLI を呼び出してください。

npx concept-atlas-dense-explain <args>

これだけが実行方法です。探すものはほかにありません。ローカルのバイナリ、リポジトリのチェックアウト、インストール済みのコピーを検索したり、フレームワーク独自の npm スクリプトを実行したりしないでください。最初の呼び出しでは npm レジストリからパッケージがダウンロードされます。そのことを一度伝えたら、続けてください。

ワークフロー

1. ページシェルを1つ選びます。atlas（ノードナビゲーション付きの概念グラフ）または scroll（連続したドキュメント）です。読者が概念を掘り下げたり、関連性をたどったりする場合は atlas、論理を順に展開する文章、チュートリアル、レポートには scroll をおすすめします。ライブラリは共通です。.mdx がすでに存在する場合は、そのシェルを検出して、それに合わせて作業してください。
2. 作成を始める前にコンポーネントを把握します。 references/components.md はカタログです。推測するのではなく、コンポーネント名で検索して、props と形状を確認してください。references/atlas-guide.mdx（atlas）または references/scroll-guide.mdx（scroll）は、各シェルのコンポーネントを組み合わせてページを構成する方法を示す、実際にコンパイル可能な MDX です。ほかの場所でコンポーネントのドキュメントを探さないでください。また、このために guide を実行しないでください。 ページと並べてコンパイルするために、プロジェクト内にコピーがどうしても必要な場合に限り、npx concept-atlas-dense-explain guide --mode <mode> -o <file> を実行し、作業が終わったらそのコピーを削除してください。
3. 必要に応じて、ひな形から始めます。npx concept-atlas-dense-explain create <file>.mdx --mode atlas|scroll（--mode のデフォルトは scroll）。create と guide は出力先の内容を上書きするため、残しておきたいファイルを指定しないでください。
4. ユーザーの .mdx ファイルに、意味に沿った MDX を記述します（作成ルールを参照）。
5. レンダリングの前に検証します。

   npx concept-atlas-dense-explain validate <file>.mdx --mode atlas|scroll
   npx concept-atlas-dense-explain validate <file>.mdx --json
   

   診断メッセージは CODE line:column message の形式です。すべての error を修正して再実行し、手間がかからない場合は警告にも対処してください。
6. コンパイルします。npx concept-atlas-dense-explain <file>.mdx --mode atlas|scroll [-o out.html] [--skin <id>] [--default-mode dark|light|system] [--style <id>]。-o を指定しない場合、MDX と同じ場所にスタンドアロン HTML が出力されます。検証エラーがあるとビルドは中止されます（--no-validate を使うと、問題があると承知のうえでビルドを強制できます）。<Mermaid> チャートは Pele でレンダリングされ、HTML にインライン化されるため、CDN の呼び出しが不要な完全オフラインの単一ファイルになります。フラグは必要ありません。
7. 外観（任意）：ページには、読者が選べる外観メニューが用意されています。パレット（aurora：インディゴ、ember：ゴールド、verdant：フォレスト、sakura：ピンクプラム、noir：インク）、ダーク／ライトの切り替え、コンポーネントスタイルパック（manuscript：編集者風の欄外注、classic：枠付きカード、shadcn：細い境界線のミニマルな UI、elastic：枠付きの可観測性パネル）を選択できます。標準のデフォルトは aurora × manuscript × light です。選択内容は localStorage に保存され、どちらのキャリアでも保持されます。--skin ember --default-mode dark --style classic（またはリポジトリのビルドで CONCEPT_ATLAS_SKIN ／ CONCEPT_ATLAS_DEFAULT_MODE ／ CONCEPT_ATLAS_STYLE）を指定すると、コンパイル時のデフォルトを別の値に設定できます。--default-mode は dark／light を受け付け、system はキャリアのデフォルト（light）に解決されます。デフォルトを設定するのは、ユーザーが指定した場合に限ってください。コンテンツ MDX で外観を設定することはありません。
8. 複数のドキュメントを扱う場合は、1回の呼び出しですべて渡します。npx concept-atlas-dense-explain a.mdx b.mdx c.mdx -o dist [--concurrency 3]（この場合、-o はディレクトリです。最初にすべてを検証してから、並列にビルドします）。ビルドに含まれるレンダラーは、コンテンツで使うものだけです。<Math> がなければ KaTeX の約 1.4MB のインラインフォントは省略され、<Mermaid> がなければ Pele は完全に除外されます。有効化するために、ダミーの <Math>／<Mermaid> ノードを追加しないでください。
9. シェル、出力先、検証結果（エラー／警告）、制約を報告します。確認していない操作について、動作すると主張しないでください。

キャリア

• atlas：ExplainPage → ConceptGraph → ConceptNode に加え、Children／ConceptRef とブランチをまたぐ Relation で構成されます。L0 のルートは必ず1つとし、複数の L1 ブランチを配置します。深さは L3／L4 までです。共有コンポーネントはノード内に配置します。ConceptNode には、ノードの知識上の役割をレベルとは独立して示す任意の kind も指定できます（「作成ルール」を参照）。
• scroll：ScrollDocument → ScrollHeader ＋ ScrollSection（＋ ScrollProse、ScrollGrid）で構成されます。共有コンポーネントはセクション内に配置します。シェルはセクションのタイトルから目次と読書の進捗を自動生成するため、ナビゲーションを手動で作成しないでください。
• ブラウザータブのタイトルはビルドフラグではなく、シェルから設定されます。ExplainPage title（atlas）または ScrollHeader title（scroll）が <title> になるため、具体的で内容に即した名前を指定してください。「主题名称」のようなプレースホルダーは使用しないでください。すべてのページで固定の 📃 ファビコンを使用します。
• 1つのMDXファイルで両方のシェルを使用しないでください。シェルを切り替える場合は、外側の構造だけを変換してください。

コンポーネントとプロパティのリファレンス

コンポーネントの一覧、すべてのプロパティの形式、構文上の注意点については、references/components.md を参照してください。作成を始める前に必ず読み、新しいタグをこのページで使うたびに、コンポーネント名で検索してください。プロパティ名や形式を推測することはできません。チャート、学習ループ、来歴、データ／動作、構造の各コンポーネントについては、同ファイルに詳細が記載されています。以下では、すべてのページで守る必要があるルールのみを再掲します。

作成ルール

• MDX のセマンティクスを保ってください。CSS、座標、SVG、置き換え用のアプリケーションコードは記述しないでください。コンポーネント名や props を作り出さないでください。
• 重要な各ノードには、主張を表すタイトル、1 文の summary、および実質的な内容（Definition、Mechanism、Example、Boundary、Evidence、モデル、チャート、数式のいずれか）を含めてください。Overview、Definition、Insight で同じ文章を繰り返さないでください。
• kind（任意、atlas）：level とは独立して、ノードの知識上の役割をタグ付けします。system、stage、mechanism、artifact、failure、tool、boundary、decision のいずれかを指定します。グラフの「知識タイプ」フィルターとノードバッジに使用されるため、役割が明確な場合に指定し、すべてのノードに指定する必要はありません。指定すると、任意の 2 つの要件が適用されます。kind="mechanism" には Invariant または Evidence を含めてください。kind="failure" には FailureMode（symptom／cause／evidence／remedy を含む）を含めてください。
• 配列 props にはオブジェクトの配列を指定してください：Flow steps={[{title, description}]}、Timeline events={[{label, content}]}、MatrixModel cells={[{title, description, tone}]}、DecisionMatrix headers={[...]} rows={[[...]]}、Chart data={[{label, value}]}、References items={[{id, authors, year, title, url, source}]}。配列 prop に文字列または配列以外を指定すると、バリデーターが警告（PROP_EXPECTS_ARRAY）を出します。
• Relation type には prerequisite、causes、produces、uses、implements、contrasts、depends-on、exception-of、precedes のいずれかを指定し、各 Relation には label が必要です。親子階層は（parent と Children／ConceptRef によって）暗黙的に表現されます。Relation で表現しないでください。
• 数式：MDX は子要素内の { ... } を式として解析するため、LaTeX は formula を使い、波括弧またはバックスラッシュを含めて渡してください：<Math formula="r_{\text{ann}} = (1 + r)^{12} - 1" />、<MathBlock formula="I(x) = -\log_2 p(x)" variables={[{symbol, description}]} />。<Math>\log_2 N</Math> のように波括弧を含まない子要素は使用できます。バリデーターは警告（MATH_CHILDREN_BRACES）を出します。
• コード：MDX が式として読み取らないよう、コードは文字列として code（または子要素）に渡し、テンプレートリテラルで囲んでください：<CodeBlock language="bash" lineNumbers>{npm run validate}</CodeBlock>。バッジ、キャプション、折り返しについては references/components.md に記載されています。
• 図：必ず alt を設定し、id と <FigureRef> を使って番号を付けてください。「図 N」と手書きしないでください。相対リンクと --inline-assets のどちらを使うかはサイズ上のトレードオフです。黙って選ぶのではなく、ユーザーと相談して決めてください。
• 引用／参考文献：<Cite id="..." /> は、<References items={...} /> 内の一致する項目の位置に基づいて [n] を表示します。atlas では、引用と References ブロックを同じノード内に置いてください。ノードの内容は、そのノードを開いたときにのみ表示されるためです。
• 続けて読みやすくする設定は、手動の CSS ではなくシェルで行います。リズムには spacing="compact|comfortable|airy"、文字サイズには fontSize="compact|normal|large|xlarge"（または数値の scale／lineHeight）を指定してください。

検証診断

validate とビルドでは CODE line:column message が出力されます。ビルドする前にすべての error を修正してください。references/diagnostics.md には、発生しうるコードが記載されており、エラーと警告が分けられています。NO_ROOT_LEVEL、MULTIPLE_ROOT_LEVEL、MECHANISM_KIND_UNVERIFIED、FAILURE_KIND_UNSTRUCTURED は、--strict を指定するとエラーに昇格する警告です。

報告する前に

• すべての error 診断を解消する（または --no-validate を明確に正当化する）。
• すべての ConceptRef、Relation のエンドポイント、および ConceptGraph root が、既存のノード ID を参照している。
• すべてのノードに title と summary があり、すべての Relation に label がある。
• <Mermaid> を含むページは、すでに完全にオフラインで動作する。Pele はインラインで提供されるため、CDN フラグは不要。
• 報告したパスに HTML ファイルが存在する。

npx がレジストリに接続できない場合は、阻害要因として報告してください。実装ファイルをスキルディレクトリにコピーしないでください。