@vicentelyrio/netherite 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vicentelyrio
+
+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.

package/README.md

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# Netherite
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A typed, linked knowledge base that lives in your git repository as Markdown files.
+
+Goals, projects, tasks, decisions (ADRs), docs and runbooks are plain `.md` files with YAML
+frontmatter, linked by ID (`[[TASK-00042]]`). You edit them in any editor, agents read and write
+them through an MCP server, and a local app shows them as boards, graphs and timelines. Everything
+is in git: there is no database, no account and no cloud.
+
+```text
+netherite/
+  goals/      GOAL-00001-run-a-marathon.md
+  projects/   PRJ-00003-training-plan.md
+  tasks/      TASK-00042-long-run.md
+  adr/        ADR-00007-use-gnu-stow.md
+  docs/       DOC-00002-shell-setup.md
+  context/    CTX-00001-house-rules.md
+  runbooks/   RUN-00004-bootstrap.md
+```
+
+## Quick start
+
+You need Node 24 or newer and a git repository.
+
+```sh
+cd my-repo
+npx @vicentelyrio/netherite init        # config, folders, .gitignore line, agent skills
+npx @vicentelyrio/netherite             # the app, at http://127.0.0.1:4747
+```
+
+To type less, install it once with `npm install --global @vicentelyrio/netherite`; the command is then just `netherite`.
+
+`init` is safe to run again. `npx @vicentelyrio/netherite serve --no-open` starts the same thing without opening
+a browser. The server listens on `127.0.0.1` only.
+
+Next: [getting started](https://vicentelyrio.github.io/netherite/getting-started) walks through creating your first goal, project
+and task, connecting an agent, and keeping the context file in sync.
+
+## What you get
+
+- **The app** (`netherite`): goals by area, a kanban board per project, a task drawer with the file
+  beside it, a knowledge index, a decision log, a graph, search (<kbd>⌘K</kbd>), an inbox, stats and
+  tags. Edits write straight to the Markdown files; nothing is committed for you.
+- **An MCP server** (`netherite mcp`): agents search, read, create and update items with the same
+  rules as the app, so an agent cannot write a malformed file.
+- **Agent skills**: `init` installs short skills into `.claude/skills/` and a section in
+  `AGENTS.md` that tell an agent how this repository tracks work.
+- **A linter** (`netherite lint`): broken links, wrong fields, ID collisions, stale docs.
+- **Freshness**: a doc that lists the code it `covers` is marked stale when that code has changed
+  in git since the doc was reviewed.
+
+## Documentation
+
+The same pages are published as a searchable site: <https://vicentelyrio.github.io/netherite/>.
+
+| | |
+| --- | --- |
+| [Getting started](https://vicentelyrio.github.io/netherite/getting-started) | `init`, the app, the first items, agents and skills |
+| [Install](https://vicentelyrio.github.io/netherite/install) | `npx` or global, upgrading, what `init` adds, troubleshooting |
+| [Agents](https://vicentelyrio.github.io/netherite/agents) | the skills, connecting Claude Code, Cursor and Codex, context |
+| [Migrate](https://vicentelyrio.github.io/netherite/migrate) | bring an existing repository's docs, ADRs and conventions in |
+| [Templates](https://vicentelyrio.github.io/netherite/templates) | a starter for each item type, `new --template`, and your own |
+| [Concepts](https://vicentelyrio.github.io/netherite/concepts) | items, IDs, links, states, freshness and context |
+| [CLI reference](https://vicentelyrio.github.io/netherite/reference/cli) | every command and flag |
+| [MCP reference](https://vicentelyrio.github.io/netherite/reference/mcp) | the tools and resources an agent sees |
+| [Item schemas](https://vicentelyrio.github.io/netherite/reference/schemas) | the fields of each item type |
+| [Import](https://vicentelyrio.github.io/netherite/reference/import) | bring existing docs, runbooks and ADRs in from a reviewed batch file |
+| [Lint rules](https://vicentelyrio.github.io/netherite/reference/lint) | what `netherite lint` reports and which problems it fixes |
+| [Configuration](https://vicentelyrio.github.io/netherite/reference/config) | `.netherite/config.yml` |
+| [Obsidian](https://vicentelyrio.github.io/netherite/obsidian) | opening the same files in Obsidian |
+
+## Developing
+
+```sh
+pnpm install
+pnpm build           # all packages and the app
+pnpm test            # unit and integration tests
+pnpm e2e             # the app in a real browser (needs `pnpm build`)
+pnpm lint
+pnpm docs:gen        # regenerate apps/docs/reference from the program
+```
+
+This repository tracks its own work in `netherite/`; the plan is in `netherite/docs/`.
+
+## Licence
+
+[MIT](LICENSE).