@haus-tech/haus-workflow 4.7.0 → 4.9.0

package/docs/before-you-start.md

@@ -0,0 +1,57 @@
+# Before you start
+
+What your machine needs before the first haus command, and what to do when one of
+them is missing. You do not need to read this if `haus doctor --prereqs` says the
+machine is ready.
+
+```bash
+haus doctor --prereqs
+```
+
+That command checks everything on this page and prints the fix beside anything that is
+missing. Run it first; come back here only for the detail.
+
+## What haus needs
+
+| You need              | What haus uses it for                            | If it is missing                                                         |
+| --------------------- | ------------------------------------------------ | ------------------------------------------------------------------------ |
+| **Node 22 or newer**  | running haus itself                              | `nvm install 22` (or install Node 22 from nodejs.org)                    |
+| **git**               | reading the project, and every worktree command  | macOS: `xcode-select --install`, or `brew install git`                   |
+| **GitHub CLI (`gh`)** | signing in to the catalog haus installs from     | `brew install gh`, then `gh auth login`                                  |
+| **A GitHub sign-in**  | the catalog repository is private                | `gh auth login` — see below                                              |
+| **Claude Code**       | the editor haus configures, and the `claude` CLI | install from <https://claude.com/claude-code>, then reopen your terminal |
+| **Network access**    | fetching the catalog                             | connect, or use an offline bundle (`docs/cli.md` → offline)              |
+
+## The one that catches everybody: signing in to GitHub
+
+haus installs its skills and agents from a **private** catalog repository. GitHub
+answers a signed-out read of a private repository with **404**, not "please sign in" —
+so if you are not signed in, the first command reports that a file could not be
+fetched, and it looks like the network or the tool is broken. It is neither.
+
+```bash
+gh auth login          # sign in once
+haus doctor --prereqs  # confirm
+```
+
+If you use a token instead of the GitHub CLI:
+
+```bash
+export GITHUB_TOKEN=$(gh auth token)   # or: export HAUS_GITHUB_TOKEN=<your token>
+```
+
+If you are signed in and the catalog still refuses, your account does not have access
+to the catalog repository yet — ask a maintainer to add you, rather than signing in
+again.
+
+## Then what
+
+```bash
+haus init      # set this project up
+haus doctor    # check the setup afterwards
+```
+
+Both are safe to re-run. `haus init` shows you what it will do before writing
+anything, and everything haus writes is backed up first.
+
+New to the vocabulary — skill, agent, hook, ADR? See [the glossary](glossary.md).

package/docs/glossary.md

@@ -0,0 +1,56 @@
+# Glossary
+
+One screen of the words haus uses, in plain language. Written for someone who is not a
+developer and does not need to become one to use this tool.
+
+**Claude Code** — the coding assistant this tool configures. haus does not replace it;
+it sets up what Claude Code reads so its answers fit your project.
+
+**Skill** — a short document that teaches the assistant how something is done here:
+how you write tests, how you name things, how a deploy goes. Installed into
+`.claude/skills/`.
+
+**Agent** — a specialist the assistant can hand a job to, like a code reviewer or a
+security reviewer. Installed into `.claude/agents/`.
+
+**Rule** — a standing instruction the assistant follows in this project, kept in
+`.claude/rules/`. Shorter than a skill and always in effect.
+
+**Command** (or slash command) — something you can invoke by name in Claude Code, like
+`/docs`. haus installs a few, and the catalog can add more.
+
+**Hook** — a check that runs automatically at a specific moment: before a command runs,
+when a session starts. haus installs hooks that block dangerous commands and stop the
+assistant reading files that hold secrets. You do not invoke a hook; it fires on its own.
+
+**Catalog** — the shared library of skills, agents, and rules that haus installs from.
+It lives in a private repository, which is why haus needs you signed in to GitHub.
+
+**Recommendation** — haus's answer to "which of those items does this project need",
+based on what it finds in the project. Stored in `.haus-workflow/recommendation.json`,
+which is deliberately not committed: it is a local answer, recomputed whenever you ask.
+
+**Lockfile** (`.haus-workflow/haus.lock.json`) — the record of what haus installed and
+which version. This one **is** committed, so everyone on the team gets the same set.
+
+**ADR** (Architecture Decision Record) — a short note recording a decision and why it
+was made, kept in `docs/decisions/`. Written once; superseded by a later ADR rather
+than edited, so the reasoning survives.
+
+**Managed file / managed block** — a file, or a marked section inside one, that haus
+writes and re-writes. Editing it by hand is not useful: the next `haus apply` restores
+haus's version, and haus tells you it found an edit. Change the source, not the output.
+
+**Apply** — writing haus's decisions to disk (`haus apply --write`). Always backs up
+first, into `.haus-workflow/backups/`.
+
+**Doctor** (`haus doctor`) — the health check. It reports what is set up, what drifted,
+and what to run to fix each finding. `haus doctor --prereqs` checks the machine
+instead of the project.
+
+**Worktree** — a second working copy of the same repository, so two pieces of work can
+proceed without disturbing each other. haus can set one up per repository in a
+workspace.
+
+**Workspace** — several repositories worked on together as one unit, described by a
+`haus.workspace.yaml`.