[codex] Initial SecondBrain framework

.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,25 @@
+name: Framework improvement
+description: Propose a reusable SecondBrain framework change
+title: "[Feature]: "
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: Describe the reusable problem without including personal vault data.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed change
+    validations:
+      required: true
+  - type: checkboxes
+    id: privacy
+    attributes:
+      label: Privacy
+      options:
+        - label: I removed personal notes, paths, identities, credentials, and private links.
+          required: true

.github/pull_request_template.md

@@ -0,0 +1,12 @@
+## What changed
+
+## Why
+
+## User impact
+
+## Privacy review
+
+- [ ] No personal content, credentials, host paths, or private links are present.
+- [ ] Publication allowlist and denylist behaviour remains fail-closed.
+
+## Validation

.github/workflows/validate.yml

@@ -0,0 +1,28 @@
+name: Validate framework
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Compile tools
+        run: python3 -m py_compile framework/tools/*.py install.py
+      - name: Run framework regression tests
+        run: python3 -m unittest discover -s tests
+      - name: Install and lint sanitized example
+        run: |
+          vault="$(mktemp -d)"
+          python3 install.py --vault "$vault"
+          python3 "$vault/tools/wiki.py" lint
+          python3 "$vault/tools/dtm.py" lint

.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+*.py[cod]
+.DS_Store

CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+This project follows Keep a Changelog principles and uses semantic versioning
+for tagged releases.
+
+## [Unreleased]
+
+### Added
+
+- Initial Knowledge Agent and Digital TeamMate framework.
+- Allowlist-only publication boundary and repeatable installer.
+- Sanitized automation definitions and empty-vault example.

CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+# Code of Conduct
+
+Be respectful, constructive, and considerate. Discuss ideas and implementations
+without attacking people. Harassment, discrimination, disclosure of private
+information, and deliberately unsafe contributions are not acceptable.
+
+Maintainers may edit or remove contributions and participation that violate
+these expectations. Serious or sensitive concerns should be reported privately
+through the repository's security reporting channel.

CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing
+
+Thank you for improving SecondBrain Framework.
+
+## Before opening a pull request
+
+1. Keep framework behaviour separate from personal vault content.
+2. Never include real Daily Notes, wiki pages, sources, activity logs, project
+   details, credentials, usernames, home-directory paths, or private links.
+3. Use synthetic examples with unmistakably fictional data.
+4. Update documentation and automation definitions alongside behavioural
+   changes.
+5. Run the validation commands below.
+
+```sh
+python3 -m py_compile framework/tools/*.py install.py
+python3 -m unittest discover -s tests
+tmpdir="$(mktemp -d)"
+python3 install.py --vault "$tmpdir"
+python3 "$tmpdir/tools/wiki.py" lint
+python3 "$tmpdir/tools/dtm.py" lint
+```
+
+Pull requests should explain the motivation, user impact, privacy implications,
+and validation performed. Prefer focused changes that can be rolled back
+independently.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SecondBrain Framework contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,2 +1,53 @@
-# secondbrain-framework
-An Obsidian-native LLM Knowledge Agent and Digital TeamMate framework
+# SecondBrain Framework
+
+An Obsidian-native personal knowledge and operational system maintained by two
+deliberately separate LLM roles:
+
+- the **LLM Knowledge Agent**, which compiles curated sources into a persistent,
+  cited wiki; and
+- the **Digital TeamMate (DTM)**, which maintains day-to-day continuity across
+  notes, tasks, projects, decisions, and follow-ups.
+
+This repository contains only the reusable framework. It contains no personal
+vault data, source material, Daily Notes, project content, or activity history.
+
+## Why this exists
+
+Most document assistants rediscover context at query time. SecondBrain instead
+maintains a durable intermediate knowledge layer and a separate operational
+memory. The division keeps long-term evidence synthesis disciplined while still
+supporting practical daily collaboration.
+
+## Quick start
+
+Requirements: Python 3.9+ and an existing or new Obsidian vault.
+
+```sh
+python3 install.py --vault /path/to/your/obsidian-vault
+```
+
+The installer copies only framework files and never copies this repository's
+`.git` directory. Existing files are preserved unless `--force` is supplied.
+After installation:
+
+1. Put a source directly in `raw/` and ask the Knowledge Agent to ingest it.
+2. Ask the DTM to open or update today's Daily Note.
+3. Review `framework/automation-definitions/` and recreate only the automations
+   appropriate for your host.
+
+See [Installation](docs/installation.md), [Architecture](docs/architecture.md),
+and [Operations](docs/operations.md) for the full model.
+
+## Privacy model
+
+The public framework is produced through an allowlist-only exporter. Personal
+content paths are denied independently of the allowlist, and the export fails
+closed when it detects live-vault Git metadata, unsafe destinations, or likely
+personal identifiers. See [Publication and versioning](docs/publication.md).
+
+## Status
+
+The framework is evolving and should be reviewed before use with sensitive or
+high-stakes information. Contributions are welcome through pull requests.
+
+Licensed under the [MIT License](LICENSE).

SECURITY.md

@@ -0,0 +1,13 @@
+# Security and privacy
+
+Please do not report a vulnerability by opening a public issue when it could
+expose personal data or credentials. Use GitHub's private vulnerability
+reporting feature for this repository.
+
+The primary safety boundary is architectural: a live personal vault is not a
+Git repository, and publication uses an explicit allowlist into a separate
+checkout. Treat any path-bypass, unintended-file export, credential exposure,
+or publication of personal content as a security issue.
+
+Before reporting, remove personal material from screenshots, logs, examples,
+and reproduction cases.

docs/architecture.md

@@ -0,0 +1,35 @@
+# Architecture
+
+SecondBrain separates operational collaboration from durable knowledge work.
+
+## Runtime layers
+
+1. **Raw sources** are human-curated evidence. Top-level files await ingestion;
+   completed sources move unchanged to `raw/processed/`.
+2. **Wiki** pages are agent-maintained syntheses with provenance, citations,
+   cross-links, an index, and an append-only operation log.
+3. **Daily operations** contain Daily Notes, tasks, decisions, project plans,
+   working documents, and recurrence state maintained by the DTM.
+4. **Schema and tools** define role boundaries, formats, workflows, validation,
+   templates, and automations.
+
+## Role boundary
+
+The Knowledge Agent owns systematic source ingestion and wiki maintenance. The
+DTM owns Daily Notes and operational continuity. The DTM does not scan the raw
+inbox, and the Knowledge Agent never writes the Daily Note activity section.
+
+## Production boundary
+
+The live Obsidian vault may be synchronized by a file service such as iCloud,
+but it is never a Git checkout. A separate repository contains a sanitized
+product representation of the framework. Publication is strictly one-way:
+
+```text
+live vault -- allowlist + privacy checks --> staged framework --> Git checkout
+```
+
+No branch, merge, worktree, or repository operation runs against the live
+vault. Rollback means restoring a reviewed framework version through the
+installer or manually applying a known-good change—not checking out history in
+production.

docs/installation.md

@@ -0,0 +1,37 @@
+# Installation
+
+## Requirements
+
+- Python 3.9 or later
+- An Obsidian vault
+- An LLM coding agent capable of reading a vault-level `AGENTS.md`
+
+## Install
+
+Clone this repository somewhere outside the vault, then run:
+
+```sh
+python3 install.py --vault /path/to/vault
+```
+
+The installer creates missing operational directories and copies framework
+contracts, templates, tools, safe Obsidian settings, recurrence defaults, and
+sanitized seed pages. It does not copy `.git` metadata and does not overwrite
+existing files by default. Preview with `--dry-run`; deliberately replace
+framework files with `--force` after reviewing the changes.
+
+## Configure
+
+1. Review `AGENTS.md` and `DTM.md` for local preferences.
+2. Keep `scratch.md` human-only or remove that convention explicitly.
+3. Edit `dtm/recurring-tasks.json`; example rules are disabled by default.
+4. Configure automation definitions for the local agent host. Replace every
+   `{{PLACEHOLDER}}`; never commit the resulting machine-specific values.
+5. Open the directory as an Obsidian vault.
+
+## Validate
+
+```sh
+python3 tools/wiki.py lint
+python3 tools/dtm.py lint
+```

docs/operations.md

@@ -0,0 +1,28 @@
+# Operations
+
+## Knowledge ingestion
+
+Place new sources directly under `raw/`. The Knowledge Agent processes each
+source, integrates its evidence across the wiki, updates the index and log,
+validates the result, then moves the unchanged source to `raw/processed/`.
+Incomplete work remains visible in the inbox.
+
+## Daily collaboration
+
+The DTM opens and closes Daily Notes, carries only incomplete tasks and active
+questions forward, instantiates enabled recurrence, captures decisions, and
+maintains project continuity. Durable knowledge can graduate to the wiki while
+remaining clearly distinguished from externally sourced evidence.
+
+## Maintenance
+
+Run both structural linters after framework changes. Periodically perform a
+semantic wiki review for contradictions, stale claims, unsupported assertions,
+orphans, and evidence gaps.
+
+## Automation
+
+Definitions under `framework/automation-definitions/` are parameterized
+documentation, not credentials or host configuration. Recreate them in the
+automation system used on the always-on host and keep machine-specific values
+out of this repository.

docs/publication.md

@@ -0,0 +1,40 @@
+# Publication and versioning
+
+## Safety properties
+
+- The live vault is never a Git repository.
+- Export starts from an explicit manifest, not an ignore file.
+- Personal content paths are denied even if accidentally allowlisted.
+- Staged text is scanned for home paths, email addresses, and live-vault
+  identifiers before touching the public checkout.
+- The target must be a separate Git checkout outside iCloud.
+- A no-change export creates no branch, commit, or pull request.
+
+## Weekly flow
+
+The publisher fetches and fast-forwards the public repository's default branch,
+builds a sanitized staging tree, and compares its content fingerprint. When a
+meaningful diff exists it creates a fingerprinted weekly branch, validates the
+export, commits, pushes, and opens an assigned draft pull request. Re-running
+the same export reuses the branch or existing pull request. If an earlier
+framework publication PR is still open, the run defers rather than creating a
+stack of noisy or competing reviews.
+
+## Review and promotion
+
+Review the generated PR with special attention to the privacy boundary,
+contracts, automation behaviour, and install output. Merge only intentional
+changes. Release tags should use semantic versioning and summarize migration
+requirements in the changelog.
+
+## Rollback
+
+Do not use Git directly in a live synchronized vault. Instead:
+
+1. identify the last known-good tag or commit in the public repository;
+2. check it out in the separate repository clone;
+3. preview restoration with `python3 install.py --vault /path --dry-run`;
+4. restore only reviewed framework files, using `--force` deliberately;
+5. validate the live system and record the rollback in its system log.
+
+Personal knowledge remains outside this version history and is unaffected.

examples/empty-vault/README.md

@@ -0,0 +1,4 @@
+# Empty SecondBrain vault example
+
+This directory contains sanitized seed scaffolding only. It contains no real
+Daily Notes, sources, projects, wiki knowledge, or activity history.

examples/empty-vault/daily/README.md

@@ -0,0 +1,4 @@
+# Daily Notes
+
+The DTM creates `YYYY-MM-DD.md` Daily Notes here. This public example contains
+no Daily Notes.

examples/empty-vault/projects/README.md

@@ -0,0 +1,4 @@
+# Projects
+
+DTM-maintained project plans live here. This public example contains no project
+information.

examples/empty-vault/raw/README.md

@@ -0,0 +1,5 @@
+# Raw source inbox
+
+Place new sources directly in this directory. After a fully successful ingest,
+the Knowledge Agent moves the unchanged source to `processed/`. This public
+example contains no source material.

examples/empty-vault/raw/assets/.gitkeep

@@ -0,0 +1 @@
+

examples/empty-vault/raw/processed/README.md

@@ -0,0 +1,4 @@
+# Processed sources
+
+Successfully ingested immutable sources live here. This public example contains
+no source material.