ray-obsidian

Ray Obsidian

Install the foundation of content production into the user's own local directory. First determine the knowledge base root directory, then audit, initialize, and review; for existing vaults, only fill in gaps incrementally.

Fixed principles

1. Do not use rays-brainby default, and do not assume the knowledge base is located in iCloud, the user's home directory, or the current project.
2. Keep raw materials, long-term knowledge, the creation process, and published finished works separate; links express relationships, directories express responsibilities.
3. The user's existing files take priority. Do not overwrite files with the same name, and do not automatically move, rename, delete, or batch-modify frontmatter.
4. Do not modify .obsidian/, and do not force plugins, sync services, Git, or a specific cloud drive. Obsidian is just an editor; ordinary Markdown tools can also use this structure.
5. Initialization only establishes a minimal usable skeleton. Collection automation, web clipping, X data, and publishing connectors are configured separately when the user needs them.
6. A check must be run after initialization; the existence of directories does not mean the knowledge base is usable.

1. Determine the knowledge base root directory

Locate it in the following order:

1. The directory explicitly provided by the user.
2. The .ray-obsidian.json。
3. A compatible knowledge base in the current directory or a parent directory that simultaneously contains 10-创作/、20-知识/、30-资料/、50-系统/ .
4. If it still cannot be determined, ask only one question: which local directory should the knowledge base be created in?

After the path is determined, first report the absolute path. Do not mistake an ordinary project directory for a knowledge base, and do not write to it directly just because the directory name contains brain、notes or vault .

2. Check first, then initialize

Run using the root directory reported when the Skill is loaded:

python3 <skill-base>/scripts/vault_setup.py check --vault <知识库目录>

When the check result is ready , deliver directly; when it is incomplete or missing , read vault-schema.md, and briefly explain to the user which directories and templates will be added. Known ray-content-v1 will be marked as upgradeable, and the current structure will be filled in through incremental initialization; unknown versions still stop.

For an existing Obsidian vault, additionally read migration.md. Only perform incremental initialization of the compatibility layer; do not organize old notes.

3. Safe initialization

Dry run first:

python3 <skill-base>/scripts/vault_setup.py init --vault <知识库目录> --name <知识库名称> --dry-run

After confirming the target has not gone off track, execute:

python3 <skill-base>/scripts/vault_setup.py init --vault <知识库目录> --name <知识库名称>

The script will only:

• Create missing directories.
• Copy missing descriptions, processes, and templates from assets/vault-template/ .
• Create .ray-obsidian.json for other Ray Skills to discover the structure version.
• Keep all existing files and list them in the results as preserved。

When files with the same name appear, the user's files take precedence. Known ray-content-v1 only upgrade the manifest, fill in missing structures, and keep all old directories and files; if the existing manifest cannot be parsed or declares an unknown structure version, stop and report, and do not overwrite to fix it.

4. Review the actual results

After initialization, run checkagain, and actually read:

• HOME.md
• 00-入口/10-工作台/知识工作台.md
• 00-入口/10-工作台/创作工作台.md
• 50-系统/30-模板/内容成稿包.md
• 50-系统/20-流程/个人知识库工作流.md

The completion status must be ready, and the script must report that no files were overwritten. When the user only asks for a check, do not take the opportunity to initialize.

5. Handover content production

Deliver the absolute path of the knowledge base to the user, and explain the three minimal entry points:

• New materials go into 30-资料/, your own immediate thoughts go into 10-创作/10-灵感/inbox.md。
• Angles worth expressing first go into 10-创作/10-灵感/20-候选选题/; after confirming the current angle, only then establish the finished draft package in 10-创作/20-写作任务/ .
• Image-and-text master drafts go into 10-创作/30-文章草稿/; master drafts written directly as spoken-word scripts go into 10-创作/20-口播草稿/; only after confirming publication do they go into 40-发布/, and are reviewed in 40-发布/00-内容反馈/ .

When the user then asks to write an article, hand the knowledge base root directory, material paths, and target platform to ray-writer. Do not copy the entire knowledge base into the Skill directory, and do not absorb user notes as Skill samples.

Completion criteria

• The root directory is determined by the user or by a verifiable structure, not guessed from directory names.
• A dry run is completed before initialization; existing files have zero overwrites, zero moves, and zero deletions.
• The manifest, directories, and core templates are complete, and the final check is ready。
• The user knows how to open this directory in Obsidian, and how to go from materials to the finished draft package and drafts.