alignfirst 0.6.0-preview.1 → 0.7.0-preview.0

package/README.md

@@ -81,6 +81,12 @@ Use your alignfirst-setup-guide skill. What AlignFirst tooling could we add in t
 
 The guide installs the selected components and configures the repository. You can remove the setup-guide skill once setup is complete.
 
+To leave the repository untouched, the guide keeps the project's AlignFirst files in a [companion directory](#companion-directories):
+
+```text
+Use your alignfirst-setup-guide skill. Set up AlignFirst in this project without touching the repository.
+```
+
 ## CLI commands
 
 - `guide` — Print an AlignFirst protocol.
@@ -101,11 +107,10 @@ Run `alignfirst --help` for command usage or `alignfirst guide` to choose a prot
 
 ## Companion directories
 
-A companion directory holds a project's AlignFirst files outside its repository, so the repository stays untouched. `~/.config/alignfirst/companions.json` declares which projects have one:
+A companion directory holds a project's AlignFirst files outside its repository, so the repository stays untouched. `~/.alignfirst/companions.json` declares which projects have one:
 
 ```json
 {
-  "root": "~/alignfirst-companions",
   "paths": {
     "~/projects/team-app": { ".plans": false, "_aligndev": true },
     "~/projects/client-api": {},
@@ -114,7 +119,6 @@ A companion directory holds a project's AlignFirst files outside its repository,
 }
 ```
 
-- `root` — the directory that holds the companion directories: an absolute path or a `~/` path.
 - `paths` — the projects, by absolute or `~/` path. Each value sets flags for the items a companion can hold: `.alignfirst.json`, `.alignfirst.md`, `DEVELOPERS.md`, `docs`, `.plans` and `_aligndev`. A flag is `true`, `false` or `"auto"`.
 
 An absent file means no project has a companion. An invalid file makes every command fail; `doctor` reports it and continues.
@@ -123,7 +127,7 @@ An absent file means no project has a companion. An invalid file makes every com
 
 A key matches a project when it names the project's main worktree or one of its ancestors, so every worktree of a project shares one companion. `"~": {}` matches every project under the home directory. For each item, the longest matching key that sets the flag wins, and an unset flag is `"auto"`. A bare repository or a directory outside git has no companion.
 
-The companion directory is `<root>/<name>`. The name is the main worktree path relative to the home directory, or the absolute path without its leading `/` outside it, with every `/` replaced by `_`. For example, `~/projects/client-api` gets `<root>/projects_client-api/`.
+The companion directory is `~/.alignfirst/companions/<name>`. The name is the main worktree path relative to the home directory, or the absolute path without its leading `/` outside it, with every `/` replaced by `_`. For example, `~/projects/client-api` gets `~/.alignfirst/companions/projects_client-api/`. To keep the companions elsewhere, make `~/.alignfirst/companions` a symlink.
 
 ### Resolution
 
@@ -146,7 +150,7 @@ The companion directory is `<root>/<name>`. The name is the main worktree path r
 An agent reads a repository's `AGENTS.md` on its own, but never a companion. When your repositories carry no AlignFirst instructions, add this line to your global agent instructions (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, or the equivalent):
 
 ```text
-In a git repository, run `alignfirst context` once before investigating, unless the project's instructions already say so.
+In a git repository, run `alignfirst context` as your first command, whatever the task, unless the project's instructions already say so.
 ```
 
 ## Upgrade from v1, v2, or v3

package/dist/project-layout.js

@@ -12,6 +12,8 @@ export const ITEM_NAMES = [
     ".plans",
     "_aligndev",
 ];
+// The directory holding the companions. A symlink there moves them elsewhere.
+const COMPANIONS_ROOT = "~/.alignfirst/companions";
 const FLAG = "boolean | 'auto'";
 const flagsSchema = type({
     "+": "reject",
@@ -24,7 +26,6 @@ const flagsSchema = type({
 });
 const companionsSchema = type({
     "+": "reject",
-    root: "string > 0",
     paths: type.Record("string", flagsSchema),
 });
 export function layoutOf(ctx) {
@@ -48,7 +49,7 @@ function resolveCompanion(cwd, home) {
         return null;
     const flags = mergeFlags(matches);
     assertValidFlags(file, flags, matches);
-    const dir = join(normalizePath(file.root, realHome), companionName(mainWorktree, realHome));
+    const dir = join(normalizePath(COMPANIONS_ROOT, realHome), companionName(mainWorktree, realHome));
     return { dir, exists: pathExists(dir), entries: matches.map((match) => match.key), flags };
 }
 function readCompanionsFile(home) {
@@ -65,15 +66,13 @@ function readCompanionsFile(home) {
     const file = companionsSchema(value);
     if (file instanceof type.errors)
         throw invalidCompanions(path, file.summary.split("\n", 1)[0]);
-    if (!isUserPath(file.root))
-        throw invalidCompanions(path, `root must be an absolute path or start with ~/: ${file.root}`);
     const badKey = Object.keys(file.paths).find((key) => !isUserPath(key));
     if (badKey !== undefined)
         throw invalidCompanions(path, `paths key must be an absolute path or start with ~/: ${badKey}`);
-    return { path, root: file.root, paths: file.paths };
+    return { path, paths: file.paths };
 }
 export function companionsPath(home) {
-    return join(home, ".config", "alignfirst", "companions.json");
+    return join(home, ".alignfirst", "companions.json");
 }
 function invalidCompanions(path, detail) {
     return new CliError(`Invalid ${path}: ${detail}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alignfirst",
-  "version": "0.6.0-preview.1",
+  "version": "0.7.0-preview.0",
   "license": "CC0-1.0",
   "author": "Thomas MUR",
   "description": "The AlignFirst CLI: protocols, work files and docs in one command.",