unhoard 0.1.0__tar.gz

unhoard-0.1.0/LICENSE

@@ -0,0 +1,176 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

unhoard-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include tests *.py *.json

unhoard-0.1.0/PKG-INFO

@@ -0,0 +1,328 @@
+Metadata-Version: 2.4
+Name: unhoard
+Version: 0.1.0
+Summary: Your X bookmarks aren't a graveyard anymore: your agent reads each one, works out why you saved it, and writes a task you start with one click.
+Author: vicennial
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/vicennial/unhoard
+Project-URL: Repository, https://github.com/vicennial/unhoard
+Project-URL: Issues, https://github.com/vicennial/unhoard/issues
+Keywords: x,twitter,bookmarks,agents,ai-agents,omnigent,claude-code,codex,productivity,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# unhoard
+
+**Made for [Omnigent](https://github.com/omnigent-ai/omnigent). Works with any agent.**
+
+Your X bookmarks aren't a graveyard anymore. Your agent reads every bookmark, works out why you saved it, and writes
+a task you can start with one click.
+
+unhoard syncs your X bookmarks into a local SQLite file, has your own agent (Claude Code, Codex, or any command that
+reads stdin and prints JSON) write "why you probably saved this" plus up to a few concrete tasks per bookmark, and shows
+them as cards on a page that only listens on your own machine. You press **Go**, **Later** or **Skip**, a few cards a
+day. Nothing starts until you press Go.
+
+[Quick start](#quick-start) · [How it works](#how-it-works) · [Why Omnigent first](#why-omnigent-first) ·
+[X API access](#x-api-access) · [Commands](#commands) · [Privacy](#privacy-and-safety) ·
+[Phone](https://github.com/vicennial/unhoard/blob/main/docs/phone.md) · [Card API](https://github.com/vicennial/unhoard/blob/main/docs/card-api.md) · [Agent commands](https://github.com/vicennial/unhoard/blob/main/docs/agent-commands.md)
+
+![unhoard: the card page turns saved posts into tasks, and Go starts one](https://raw.githubusercontent.com/vicennial/unhoard/main/docs/images/demo.gif)
+
+> Status: **v0.1, experimental.** Apache-2.0 licensed. Python 3.11 or newer, no dependencies.
+
+## Why
+
+Saving a post takes one tap; acting on it takes a decision you never get around to. Bookmarks pile up because the
+"why" is lost the day after. unhoard keeps the part that is cheap for a person (deciding) and hands the expensive part
+to your agent: reading the post, remembering why it mattered to *you*, and turning that into a task with a brief the
+agent can start on.
+
+- **It writes the why, not a summary.** A second pass looks at your notes, memory folders and recent repositories
+  (only the ones you listed) to connect the post to your actual work.
+- **It is a short queue, not another inbox.** Three cards a day by default; the rest wait.
+- **Safe by construction.** The agent that reads the untrusted post never sees your files, and the agent that sees
+  your files never sees the post or the web. See [Privacy and safety](#privacy-and-safety).
+- **Local first.** SQLite on your disk, a server on `127.0.0.1`, your X login in a 0600 file.
+
+## How it works
+
+1. **Sync.** `unhoard sync` pulls your bookmarks from the X API into a local SQLite file (incremental, idempotent).
+2. **Your agent writes the why and the task.** `unhoard enrich` runs your agent in two passes per bookmark: one reads the
+   post, one connects it to your context. Out come "why you probably saved this" and proposed tasks, ranked
+   (priority, then confidence, then newest).
+3. **Press Go.** `unhoard serve` opens the card page. Go starts the task: as a **session in the "X Bookmarks" project in
+   Omnigent**, or by **running your own command** with the brief on stdin, or, with neither set up, by **showing the
+   brief** so you can paste it anywhere. Later hides the card for a few days; Skip drops it.
+
+![The card page with fictional demo posts: today's three picks, each with a Show brief (Go), Later and Skip button](https://raw.githubusercontent.com/vicennial/unhoard/main/docs/images/cards.png)
+
+*The page above is `unhoard try` with the fictional sample data; there the first button says "Show brief" because nothing
+is set up to start a task (with Omnigent or your command it says "Go"). The demo people, posts, numbers and links are made up:
+their handles contain a dot, which X handles cannot, so none of them is a real account, and the portraits are
+AI-generated (Nano Banana Pro) and show nobody real.*
+
+## Quick start
+
+Python 3.11 or newer. There are no dependencies.
+
+**Look first, with no account and nothing saved on your machine** (uses a temporary folder with fictional sample
+cards, and removes it when you stop):
+
+```bash
+uvx unhoard try
+# or, straight from the repository:
+uvx --from git+https://github.com/vicennial/unhoard unhoard try
+```
+
+**Install:**
+
+```bash
+uv tool install unhoard            # or: pipx install unhoard
+# or straight from the repository:
+uv tool install git+https://github.com/vicennial/unhoard    # or: pipx install git+https://github.com/vicennial/unhoard
+```
+
+**Use your own bookmarks:**
+
+```bash
+unhoard setup               # writes the config, asks a few questions, finds Omnigent, your notes and repos
+unhoard login x             # opens X in your browser; needs your own X developer app (see X API access)
+unhoard sync                # pull your bookmarks
+unhoard enrich --limit 5    # have your agent write the why and the tasks (a few first, to check the cost)
+unhoard serve               # http://127.0.0.1:8765
+```
+
+`unhoard doctor` checks what each enrichment agent can really do (a few tiny agent calls) and what Go will do.
+`unhoard demo` adds the fictional sample cards to your own database if you want to look around before you have synced.
+Run `sync` and `enrich` on a schedule with [cron, a Claude Code `/loop`, or Hermes cron](https://github.com/vicennial/unhoard/tree/main/examples/schedule/).
+
+Open <http://127.0.0.1:8765>. Today's picks are a row of stations, each with the post as it looks on X, why you
+probably saved it, the task with its brief and any links in it, a note field and the **Go / Later / Skip** buttons.
+The rest wait in a list below; open any row to answer it in place. It works at phone width (through your own port
+forwarding if you want it; the server only ever listens on loopback). `next` and `decide` do the same in a terminal.
+
+### What Go does
+
+Set `[launch] adapter` in `config.toml`. The default is `auto`:
+
+- `auto` (default): an Omnigent session when `[omnigent] agent_id` is set **and** the Omnigent API answers on this machine
+  when you press the button; otherwise it shows the brief. `unhoard setup` and `unhoard agents` find your local Omnigent
+  and save the agent you pick. An explicit adapter below always wins.
+- `omnigent`: always create a session on your Omnigent server with the task brief as the first message
+  (`POST {api}/v1/sessions`). Set `[omnigent] agent_id` to a registered agent (`unhoard agents` lists them;
+  `host_id`, `workspace`, `harness`, `model` and `reasoning_effort` are optional). Sessions go into the Omnigent
+  project (sidebar folder) named by `project`, "X Bookmarks" by default, created on the first Go; `project = ""` for none.
+  The session id is shown on the card page under "Launched".
+- `command`: pipe the brief to a program you name (an argv list, detached). This is how any other agent runs your tasks.
+- `print`: show the brief on the page (plain text, with a Copy button) and in the terminal running the server, so
+  you can paste it anywhere.
+
+The button says **Go** when it starts something (an Omnigent session or your command) and **Show brief** when it only
+shows the brief. If Omnigent starts or stops after the page loaded, the server refuses the click instead of doing
+something else (the page reloads and the button changes; nothing starts and the card stays). With `auto`, an agent
+chosen and Omnigent not running, `unhoard decide ... go` fails and the card goes back to the queue. A failed launch puts the card back in the queue and shows the reason. `status` and `doctor` show the
+configured adapter and the one that applies now.
+
+### From your phone
+
+You can start and answer cards from your phone over your own private network. It is opt-in: the server still listens
+on `127.0.0.1` only, and nothing changes unless you set it up. The recommended route is Tailscale:
+
+```bash
+unhoard phone                     # prints the steps for this machine; changes nothing
+unhoard phone --yes               # also writes [server] allowed_hosts to your config
+tailscale serve --bg 8765         # you run this, to share the page with your tailnet (never `funnel`)
+```
+
+![The brief panel on a phone after pressing Show brief](https://raw.githubusercontent.com/vicennial/unhoard/main/docs/images/phone-brief.png)
+
+Anyone on your tailnet can press Go, so share it only with people you trust. An SSH tunnel works with no config
+change. Details and the security notes: [docs/phone.md](https://github.com/vicennial/unhoard/blob/main/docs/phone.md).
+
+## Why Omnigent first
+
+[Omnigent](https://github.com/omnigent-ai/omnigent) gives each task a visible, resumable session in one project
+folder ("X Bookmarks"), in the same web UI you already use for your other Omnigent sessions. You press Go, the task
+shows up as a session you can open, watch, steer and come back to later, instead of vanishing into a terminal.
+
+Other agents work through the `command` adapter: unhoard starts your program with the brief on stdin, so any agent CLI
+or script that takes a prompt on stdin fits. They get the same brief; they just don't get the session list.
+
+### Coming: an Omnigent sidebar tab
+
+A **Bookmarks** entry in the Omnigent sidebar is planned. It needs Omnigent extension API support that does not exist
+yet: starting sessions from an extension page, and reading a local data source. Until then, use the card page.
+`src/unhoard_ext/` holds a scaffold that only explains this.
+
+## X API access
+
+You need your own X API access and your own X developer app (OAuth 2.0 enabled; "Native App" is fine). Easiest: set the
+app's callback URL to `http://127.0.0.1:8766/callback`, then run `X_CLIENT_ID=... unhoard login x` and approve it in the
+browser. The login is kept in a 0600 file in the data dir and refreshed automatically; `unhoard logout x` removes it.
+Setup and security notes: [docs/x-login.md](https://github.com/vicennial/unhoard/blob/main/docs/x-login.md). Instead, you can still export `X_BEARER_TOKEN` or
+set `[x] bearer_token`; those win over a saved login. `status` and `doctor` show which one is used, never the token.
+
+Reading bookmarks (`GET /2/users/{id}/bookmarks`) needs an **OAuth 2.0 user-context token with the `bookmark.read`
+scope**, which typically needs a paid X API plan (check X's current pricing). An app-only bearer token does not work.
+X does not return *when* you bookmarked a post, so the page shows when the post was published. If you cannot use the
+API, `sync --from-file` accepts a saved response in the same JSON shape.
+
+## Paste this into Claude Code or Codex to install and configure it
+
+```text
+Install and configure unhoard from this repository for me.
+1. Check Python >= 3.11, then run `pip install .` in a virtual environment and show me the path of
+   the `unhoard` command.
+2. Run `unhoard setup`. For "agent that writes the cards" use the CLI I am running right now.
+3. Run `unhoard demo` then `unhoard serve` and tell me the URL so I can look.
+4. Ask me whether I have X API access with a user token that has the bookmark.read scope. Do not ask me to
+   paste the token into this chat: tell me to `export X_BEARER_TOKEN=...` in my own shell or put it in a
+   600-mode env file, and wait.
+5. When I confirm, run `unhoard sync`, then `unhoard enrich --limit 5`, then
+   `unhoard status`, and summarise the result.
+6. Run `unhoard doctor` and show me the table. Review the `[context]` lists that setup wrote with
+   me. Setup run without a terminal does not save agent memory folders or memory MCP servers: show me what
+   `unhoard context discover --dry-run` found and let me decide whether to run it with `--yes`.
+   Optionally ask for a short text file about my work and set [enrich] about_me_file to it.
+7. Offer to add a schedule from examples/schedule/. Never answer cards for me and never run
+   `unhoard decide`: only I decide.
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `try [--port N] [--no-open]` | The card page with fictional sample cards in a temporary folder that is removed on exit. Touches none of your own config or data; Go only shows the brief. |
+| `setup [--yes] [--force] [--no-discover]` | Writes `config.toml` (mode 0600; asks about your X user id, agent and launch adapter on a terminal), looks for a local Omnigent and your agents, then runs `context discover`. |
+| `login x [--client-id ID] [--port N] [--timeout SECONDS] [--no-browser] [--replace]` | Logs in to X in the browser (OAuth 2.0 + PKCE). `--timeout` is how long to wait for the browser (default 300 s). If a login is saved, it asks `[y/N]` before signing it out; with no terminal it refuses unless you pass `--replace`. `logout x` revokes and deletes the saved login. |
+| `context discover [--yes] [--dry-run]` | Finds memory folders, notes, repos and memory servers and saves them to `[context]`. Without a terminal and without `--yes` it does not save agent memory folders or memory MCP servers. |
+| `phone [--host NAME] [--port N] [--yes]` | Prints the steps to use the card page from your phone over Tailscale (or SSH). Reads this machine's Tailscale name; changes nothing unless `--yes` writes `[server] allowed_hosts`. |
+| `agents [--yes]` | Lists the agents on your local Omnigent server and saves the one Go should start. |
+| `doctor` | Shows what Go will do, then starts each enrichment pass with a trivial prompt and checks the tools it really has. |
+| `sync [--full] [--refresh] [--max-items N] [--from-file JSON]` | Pulls new bookmarks. `--refresh` re-reads the pages and updates avatars, counts, media and links of bookmarks you already have (no decision or enrichment changes). `--from-file` ingests a saved X API response. |
+| `enrich [--limit N] [--retry-errors]` | Has your agent write why-saved notes and tasks for unprocessed bookmarks. |
+| `next [--more] [--json]` | Shows the best open card. `--more` ignores the daily limit. |
+| `decide ID go\|later\|skip [--note ...]` | Answers a card. Go runs the launch adapter; a failed launch puts the card back. |
+| `serve [--port N] [--no-open]` | The card page on 127.0.0.1. |
+| `status` | Paths, counts, token present (yes/no) and its source, the agent, the configured and effective launch adapter, context and MCP tools in use, config problems. |
+| `demo` | Adds fictional sample cards to your database. |
+
+## Configuration
+
+`unhoard setup` writes a commented `config.toml`. Main settings:
+
+- `[enrich] agent = "claude" | "codex"`: the program builds both agent commands when it runs, so fixes reach
+  you. `read_command` / `relate_command` (argv lists, prompt on stdin, JSON on stdout) remain as custom
+  overrides. Details and the Codex caveats are in [docs/agent-commands.md](https://github.com/vicennial/unhoard/blob/main/docs/agent-commands.md).
+- `[context]`: what pass 2 may use to connect a post to your work. `setup` and
+  `unhoard context discover` fill it in for you (see below); `status` shows what is in use.
+  `[enrich] about_me_file` is optional.
+- `[queue] daily_cards = 3`, `later_days = 3`.
+- `[server] allowed_hosts = []`: extra host names the card page answers to (default none: loopback only). For phone access, see [From your phone](#from-your-phone). Host names only: no scheme, port, wildcard or IP address. Requests by such a name must come through an HTTPS proxy (`tailscale serve`), never with the server's own port, and carry Tailscale's identity header.
+- `[server] require_tailscale_identity = true`: set `false` only behind another HTTPS proxy you trust; it turns off the identity-header check (see [docs/phone.md](docs/phone.md)).
+- `[launch] adapter`: `auto` (default: Omnigent when it runs and an agent is chosen, else show the brief), `print` (show the brief), `command` (pipe it to a program you name, detached),
+  or `omnigent` (create a session: `POST {api}/v1/sessions` with your `agent_id`, in the `project` folder,
+  default "X Bookmarks"; optional `host_id`, `workspace`, `harness`, `model`).
+
+Where things live: data in `$UNHOARD_HOME` (else the XDG data dir), config in
+`$UNHOARD_CONFIG` (else `~/.config/unhoard/config.toml`). Paths are resolved to
+absolute form once. **Agents and cron jobs may run with a different HOME than your shell, so export both
+variables for them.** The schedule examples do this.
+
+Run it on a schedule with [cron, a Claude Code `/loop`, or Hermes cron](https://github.com/vicennial/unhoard/tree/main/examples/schedule/).
+
+## What it reads by default
+
+Only what `setup` / `context discover` lists in `[context]` after you accepted it (and you can edit it):
+
+- agent memory folders (`~/.claude/projects/*/memory`, `~/.codex/memories`), note vaults (Obsidian, Logseq,
+  `~/notes`) and Git repositories you committed to in the last 30 days;
+- `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md` and each memory folder's `MEMORY.md`, inlined (capped);
+- read-only search tools of memory MCP servers you already have, if they are known ones (`gbrain`,
+  `basic-memory`, the `memory` knowledge-graph server). Other servers are never used unless you list their
+  tools yourself. A cloud-hosted memory server receives the search text, which is your own provider.
+
+Only the relate pass sees these, and it has no network. The raw post never reaches it (only pass 1's checked summary does), and the read pass
+never sees any of it. Neither Claude pass loads your own Claude customization (CLAUDE.md, hooks, settings,
+plugins, skills); `doctor` checks that. Codex supports folders but no MCP, and needs a working Linux sandbox for
+its relate pass (`doctor` checks it).
+
+The Claude presets use `--no-chrome`; they are tested with Claude Code 2.1.303 (an older version may lack the flag).
+
+## Privacy and safety
+
+- Everything is local: a SQLite file (mode 600) on your machine and a server on `127.0.0.1`.
+- The **only** place bookmark text leaves your machine is the agent command *you* configure, which may
+  send it to a model provider. The X token is removed from that command's environment, and the command
+  runs in a scratch directory, not in your projects.
+- **No agent gets all three of untrusted text, your private data and a way to send data out.**
+  Enrichment runs in two passes. Pass 1 reads the post (and the web) but never sees your files or notes.
+  Pass 2 sees your context but only a checked summary of the post, and has local read tools and no
+  network. Built-in presets are constructed to keep that rule and start without your Claude settings, CLAUDE.md,
+  hooks or allow rules, and with Claude in Chrome and claude.ai connectors off. The program refuses to start a
+  custom Claude command that breaks the rule or uses a flag it does not know (only the per-pass
+  `allow_private_in_read` / `allow_network_in_relate` overrides lift that), and warns when it cannot read a
+  custom command at all. `unhoard doctor` verifies the real behaviour. Details in
+  [docs/agent-commands.md](https://github.com/vicennial/unhoard/blob/main/docs/agent-commands.md).
+- Profile pictures, photos and video are fetched by your browser from X's servers (`pbs.twimg.com`,
+  `video.twimg.com`); the page's content-security policy allows nothing else. Set `[server] show_media = false`
+  to turn all of that off.
+- **Bookmark text is untrusted input.** It is fenced as data in the enrichment prompt, the answer is
+  validated field by field before it is stored, the card page renders text without HTML, and the launch
+  brief repeats the warning and fences the model-written task as derived data. Nothing starts until you press Go.
+  The card page marks every URL the relate agent wrote into a task, so you can look at it before you press Go.
+- The card server checks the Host header (DNS rebinding), rejects foreign Origins, and requires a custom
+  header on every state-changing request.
+
+## Layout
+
+```
+src/unhoard/
+  config.py  store.py      paths, config.toml, SQLite schema
+  sync.py                  X API v2 bookmarks -> SQLite
+  enrich.py                two-pass prompts, context pack, command plan, strict validation
+  postdata.py              avatar, counts, media and readable text from the X API objects
+  agents.py  mcp.py        agent presets and the custom-command guard; memory-MCP registry and config file
+  procs.py                 run a helper in its own process group (killed on timeout)
+  discover.py  tomledit.py context discovery and the atomic config edit that saves it
+  doctor.py                the doctor checks
+  queue.py                 ranking, daily limit, Go / Later / Skip, launched sessions
+  launch/                  auto | omnigent | command | print adapters, the target resolver and the brief template
+  netsafe.py               HTTP openers that refuse redirects (and ignore proxies for loopback probes)
+  server.py  web/          the card page (stdlib http.server + static files)
+  cli.py                   the unhoard command
+src/unhoard_ext/  Omnigent extension scaffold (manifest + a page that explains what is missing)
+examples/schedule/         cron, Claude Code /loop, Hermes cron
+```
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests     # no network, no real agent calls
+UNHOARD_LIVE=1 python3 -m unittest discover -s tests   # also runs a live smoke test against claude/codex
+```
+
+The extension-manifest test is skipped unless `omnigent` is importable in the same environment.
+
+## Known limits (v0.1)
+
+- The Omnigent extension tab is a scaffold; see "Coming" above.
+- Re-enriching a bookmark replaces its undecided proposals; decided ones are kept.
+- Only bookmarks are read: no folders, likes or lists.