edify-agents-cli 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (126) hide show
  1. edify_agents_cli-0.2.0/.gitignore +24 -0
  2. edify_agents_cli-0.2.0/CHANGELOG.md +409 -0
  3. edify_agents_cli-0.2.0/INSTALL.md +242 -0
  4. edify_agents_cli-0.2.0/LICENSE +21 -0
  5. edify_agents_cli-0.2.0/PKG-INFO +408 -0
  6. edify_agents_cli-0.2.0/README.md +359 -0
  7. edify_agents_cli-0.2.0/edify/commands/build.md +64 -0
  8. edify_agents_cli-0.2.0/edify/commands/plan.md +68 -0
  9. edify_agents_cli-0.2.0/edify/commands/spec.md +63 -0
  10. edify_agents_cli-0.2.0/edify/commands/tasks.md +65 -0
  11. edify_agents_cli-0.2.0/edify/commands/verify.md +67 -0
  12. edify_agents_cli-0.2.0/edify/formats/plan.example.md +455 -0
  13. edify_agents_cli-0.2.0/edify/formats/plan.format.md +128 -0
  14. edify_agents_cli-0.2.0/edify/formats/spec.example.md +483 -0
  15. edify_agents_cli-0.2.0/edify/formats/spec.format.md +116 -0
  16. edify_agents_cli-0.2.0/edify/formats/tasks.example.md +712 -0
  17. edify_agents_cli-0.2.0/edify/formats/tasks.format.md +199 -0
  18. edify_agents_cli-0.2.0/edify/harvest/harvest.md +91 -0
  19. edify_agents_cli-0.2.0/edify/harvest/sources.md +295 -0
  20. edify_agents_cli-0.2.0/edify/harvest/vocab.md +52 -0
  21. edify_agents_cli-0.2.0/edify/manifest.md +30 -0
  22. edify_agents_cli-0.2.0/edify/mcp/default-registry.md +66 -0
  23. edify_agents_cli-0.2.0/edify/skills/adversary.md +61 -0
  24. edify_agents_cli-0.2.0/edify/skills/debugger.md +64 -0
  25. edify_agents_cli-0.2.0/edify/skills/implementer-general.md +53 -0
  26. edify_agents_cli-0.2.0/edify/skills/implementer-go.md +63 -0
  27. edify_agents_cli-0.2.0/edify/skills/implementer-node.md +61 -0
  28. edify_agents_cli-0.2.0/edify/skills/implementer-postgres.md +63 -0
  29. edify_agents_cli-0.2.0/edify/skills/implementer-python.md +65 -0
  30. edify_agents_cli-0.2.0/edify/skills/implementer-react.md +65 -0
  31. edify_agents_cli-0.2.0/edify/skills/planner.md +58 -0
  32. edify_agents_cli-0.2.0/edify/skills/test-writer-node.md +64 -0
  33. edify_agents_cli-0.2.0/edify/skills/test-writer-python.md +60 -0
  34. edify_agents_cli-0.2.0/edify/skills/verifier.md +67 -0
  35. edify_agents_cli-0.2.0/edify/templates/CLAUDE.md +18 -0
  36. edify_agents_cli-0.2.0/pyproject.toml +79 -0
  37. edify_agents_cli-0.2.0/src/edify/__init__.py +19 -0
  38. edify_agents_cli-0.2.0/src/edify/__main__.py +6 -0
  39. edify_agents_cli-0.2.0/src/edify/_toml.py +286 -0
  40. edify_agents_cli-0.2.0/src/edify/agents.py +261 -0
  41. edify_agents_cli-0.2.0/src/edify/anim.py +499 -0
  42. edify_agents_cli-0.2.0/src/edify/assets.py +77 -0
  43. edify_agents_cli-0.2.0/src/edify/cli.py +681 -0
  44. edify_agents_cli-0.2.0/src/edify/commands/__init__.py +1 -0
  45. edify_agents_cli-0.2.0/src/edify/commands/check_cmd.py +72 -0
  46. edify_agents_cli-0.2.0/src/edify/commands/doctor_cmd.py +206 -0
  47. edify_agents_cli-0.2.0/src/edify/commands/feedback_cmd.py +90 -0
  48. edify_agents_cli-0.2.0/src/edify/commands/governance_cmd.py +65 -0
  49. edify_agents_cli-0.2.0/src/edify/commands/graph_cmd.py +156 -0
  50. edify_agents_cli-0.2.0/src/edify/commands/harvest_cmd.py +538 -0
  51. edify_agents_cli-0.2.0/src/edify/commands/init_cmd.py +333 -0
  52. edify_agents_cli-0.2.0/src/edify/commands/init_new_cmd.py +151 -0
  53. edify_agents_cli-0.2.0/src/edify/commands/license_cmd.py +80 -0
  54. edify_agents_cli-0.2.0/src/edify/commands/mcp_cmd.py +159 -0
  55. edify_agents_cli-0.2.0/src/edify/commands/self_cmd.py +185 -0
  56. edify_agents_cli-0.2.0/src/edify/commands/setup_cmd.py +79 -0
  57. edify_agents_cli-0.2.0/src/edify/commands/skills_cmd.py +177 -0
  58. edify_agents_cli-0.2.0/src/edify/commands/upgrade_cmd.py +178 -0
  59. edify_agents_cli-0.2.0/src/edify/context.py +57 -0
  60. edify_agents_cli-0.2.0/src/edify/conventions.py +275 -0
  61. edify_agents_cli-0.2.0/src/edify/detect.py +313 -0
  62. edify_agents_cli-0.2.0/src/edify/distribution.py +40 -0
  63. edify_agents_cli-0.2.0/src/edify/errors.py +66 -0
  64. edify_agents_cli-0.2.0/src/edify/feedback.py +207 -0
  65. edify_agents_cli-0.2.0/src/edify/formats/__init__.py +11 -0
  66. edify_agents_cli-0.2.0/src/edify/formats/check.py +573 -0
  67. edify_agents_cli-0.2.0/src/edify/formats/document.py +238 -0
  68. edify_agents_cli-0.2.0/src/edify/formats/finding.py +50 -0
  69. edify_agents_cli-0.2.0/src/edify/formats/fix.py +114 -0
  70. edify_agents_cli-0.2.0/src/edify/formats/mcp.py +126 -0
  71. edify_agents_cli-0.2.0/src/edify/formats/plan.py +151 -0
  72. edify_agents_cli-0.2.0/src/edify/formats/skill.py +139 -0
  73. edify_agents_cli-0.2.0/src/edify/formats/spec.py +164 -0
  74. edify_agents_cli-0.2.0/src/edify/formats/tasks.py +321 -0
  75. edify_agents_cli-0.2.0/src/edify/governance.py +316 -0
  76. edify_agents_cli-0.2.0/src/edify/graph/__init__.py +11 -0
  77. edify_agents_cli-0.2.0/src/edify/graph/extract.py +351 -0
  78. edify_agents_cli-0.2.0/src/edify/graph/ignore.py +107 -0
  79. edify_agents_cli-0.2.0/src/edify/graph/langs/__init__.py +93 -0
  80. edify_agents_cli-0.2.0/src/edify/graph/langs/ctags.py +145 -0
  81. edify_agents_cli-0.2.0/src/edify/graph/langs/markdown.py +41 -0
  82. edify_agents_cli-0.2.0/src/edify/graph/langs/patterns.py +361 -0
  83. edify_agents_cli-0.2.0/src/edify/graph/langs/python_ast.py +154 -0
  84. edify_agents_cli-0.2.0/src/edify/graph/langs/sqlish.py +86 -0
  85. edify_agents_cli-0.2.0/src/edify/graph/model.py +102 -0
  86. edify_agents_cli-0.2.0/src/edify/graph/queries.py +211 -0
  87. edify_agents_cli-0.2.0/src/edify/graph/store.py +157 -0
  88. edify_agents_cli-0.2.0/src/edify/harvest/__init__.py +28 -0
  89. edify_agents_cli-0.2.0/src/edify/harvest/ledger.py +191 -0
  90. edify_agents_cli-0.2.0/src/edify/harvest/screen.py +236 -0
  91. edify_agents_cli-0.2.0/src/edify/harvest/sources.py +298 -0
  92. edify_agents_cli-0.2.0/src/edify/host.py +345 -0
  93. edify_agents_cli-0.2.0/src/edify/interview.py +354 -0
  94. edify_agents_cli-0.2.0/src/edify/library.py +176 -0
  95. edify_agents_cli-0.2.0/src/edify/licensing/__init__.py +30 -0
  96. edify_agents_cli-0.2.0/src/edify/licensing/ed25519.py +154 -0
  97. edify_agents_cli-0.2.0/src/edify/licensing/projects.py +223 -0
  98. edify_agents_cli-0.2.0/src/edify/licensing/tier.py +172 -0
  99. edify_agents_cli-0.2.0/src/edify/licensing/token.py +149 -0
  100. edify_agents_cli-0.2.0/src/edify/paths.py +282 -0
  101. edify_agents_cli-0.2.0/src/edify/selfinstall.py +244 -0
  102. edify_agents_cli-0.2.0/src/edify/skills.py +108 -0
  103. edify_agents_cli-0.2.0/src/edify/tsv.py +109 -0
  104. edify_agents_cli-0.2.0/src/edify/ui.py +334 -0
  105. edify_agents_cli-0.2.0/tests/conftest.py +140 -0
  106. edify_agents_cli-0.2.0/tests/test_anim.py +324 -0
  107. edify_agents_cli-0.2.0/tests/test_cli.py +224 -0
  108. edify_agents_cli-0.2.0/tests/test_detect.py +71 -0
  109. edify_agents_cli-0.2.0/tests/test_feedback.py +168 -0
  110. edify_agents_cli-0.2.0/tests/test_fix.py +122 -0
  111. edify_agents_cli-0.2.0/tests/test_formats.py +347 -0
  112. edify_agents_cli-0.2.0/tests/test_governance.py +142 -0
  113. edify_agents_cli-0.2.0/tests/test_graph.py +143 -0
  114. edify_agents_cli-0.2.0/tests/test_harvest.py +454 -0
  115. edify_agents_cli-0.2.0/tests/test_host.py +291 -0
  116. edify_agents_cli-0.2.0/tests/test_init_new.py +415 -0
  117. edify_agents_cli-0.2.0/tests/test_library.py +135 -0
  118. edify_agents_cli-0.2.0/tests/test_license_cmd.py +45 -0
  119. edify_agents_cli-0.2.0/tests/test_licensing.py +170 -0
  120. edify_agents_cli-0.2.0/tests/test_mixed_versions.py +56 -0
  121. edify_agents_cli-0.2.0/tests/test_platform.py +108 -0
  122. edify_agents_cli-0.2.0/tests/test_projects_retired.py +50 -0
  123. edify_agents_cli-0.2.0/tests/test_selection.py +171 -0
  124. edify_agents_cli-0.2.0/tests/test_self.py +279 -0
  125. edify_agents_cli-0.2.0/tests/test_toml.py +86 -0
  126. edify_agents_cli-0.2.0/tests/test_ui.py +175 -0
@@ -0,0 +1,24 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .pytest_cache/
4
+ .venv/
5
+ venv/
6
+ dist/
7
+ build/
8
+ *.egg-info/
9
+ .edify/graph/
10
+ .coverage
11
+ htmlcov/
12
+ .DS_Store
13
+ tools/.keys/
14
+ # Every licence issued, with the customer's email. Local, append-only, never committed.
15
+ tools/.issued.tsv
16
+
17
+ # A stranger's text, verbatim, awaiting a human. The permanent record of what
18
+ # arrived and what happened to it is harvest/ledger.json, not the bytes.
19
+ harvest/staging/
20
+ harvest/quarantine/
21
+
22
+ # The public repository, built from this tree by copying. It carries its own
23
+ # git history and is pushed separately, so it must not be tracked here as well.
24
+ edify_public/
@@ -0,0 +1,409 @@
1
+ # Changelog
2
+
3
+ All notable changes to `edify-agents-cli`. The format follows Keep a Changelog; versioning
4
+ is semantic on the CLI surface.
5
+
6
+ Two contract versions move independently of the CLI version and are recorded in
7
+ `.edify/graph/meta` and `edify/manifest.md`: `graph-schema` (bumping it rebuilds an
8
+ existing graph rather than misreading it) and `index-schema`.
9
+
10
+ ## 0.2.0
11
+
12
+ - **Renamed** on PyPI from `edify-cli`, a name that belongs to another project, to
13
+ `edify-agents-cli`.
14
+ - Removed: the individual paid plan (`pro`), the purchase and project-count
15
+ subcommands, and the graph, project and upgrade caps.
16
+ - Changed: a second MCP server needs a team or partner licence, and existing entries are
17
+ kept.
18
+ - Docs: the README and `docs/` now carry the site's ink clips as animated WebP
19
+ (`assets/motion/`), and the terminal screenshots are recaptured from 0.2.0 output.
20
+
21
+ ## [Unreleased]
22
+
23
+ ### The ship release — a real issuing key, `edify self update`, the ∞, and a way to pay
24
+
25
+ Four things stood between EDIFY and a person paying for it. They all land here.
26
+
27
+ #### A real issuing key
28
+
29
+ `DEFAULT_PUBLIC_KEY_HEX` shipped in 0.1.0 as the public key of an **all-zeros seed**.
30
+ Anyone could mint a `pro` or `team` token with 32 zero bytes. It has been replaced with
31
+ a real random key whose private half never enters this repository, and
32
+ `tests/test_licensing.py` now fails if a key derivable from any trivially-guessable seed
33
+ comes back — by revert, by bad merge, or by a placeholder left in.
34
+
35
+ Tokens carry `exp`, so anything issued against the old key simply stops verifying. That
36
+ is the desired outcome and not a migration.
37
+
38
+ #### `edify self update` — the CLI can update itself
39
+
40
+ `edify upgrade` pulls a newer **skill library**. It could not put an edited checkout
41
+ behind the `edify` binary, and nothing else could either.
42
+
43
+ - **`edify self update [--from PATH]`** shells out to whichever tool put `edify` on
44
+ PATH — uv, pipx, or pip — because only that tool can correctly replace it. A hardcoded
45
+ `pip install` into a uv tool environment produces a second, shadowed copy, which is
46
+ the worst possible outcome for a command named "update".
47
+ - **`edify self where`** prints which binary is answering, its interpreter, prefix,
48
+ package path, detected installer, and source checkout — before anything is installed.
49
+ - Detection reads `sys.prefix` path segments (`uv/tools/…`, `pipx/venvs/…`); `--manager`
50
+ overrides it, so a mis-detection costs one flag rather than a broken install. After a
51
+ successful install the *new* binary is asked for its version, so a shadowed copy shows
52
+ up as a version that did not move.
53
+ - `--dry-run` prints the exact argv and changes nothing — the same argv the real run
54
+ uses, from the same function, so it can be trusted.
55
+ - **On Windows the running `edify.exe` may be locked.** That failure is detected and
56
+ reported with the exact command to run from another shell, never as a success it did
57
+ not have.
58
+ - **This is the second command that can reach the network**, because building a wheel
59
+ fetches `hatchling` unless it is cached. Said out loud in the module docstring rather
60
+ than quietly breaking the claim in `cli.py`; `--offline` fails cleanly instead.
61
+ - It never touches `.edify/` in any repository. That is `edify setup . --fresh`, and the
62
+ closing line says so.
63
+
64
+ #### The install has a face
65
+
66
+ `edify init` and `edify setup` did real work and printed nothing while doing it.
67
+
68
+ - **An ASCII wordmark** opens every install, once — `setup` and `init new` print it and
69
+ tell `init_cmd` not to print a second, mirroring the existing `caller_closes`.
70
+ - **An animated ∞** paints to stderr while extraction, skill install, and host mirroring
71
+ run. It is a **lemniscate of Gerono** (`x = cos t`, `y = sin 2t / 2`), which is evenly
72
+ parameterised, so a constant-speed head reads as constant-speed motion; Bernoulli's
73
+ crowds at the origin and looks like a stutter.
74
+ - **Precomputed frames, not a live plotter.** `dependencies = []` is a hard constraint,
75
+ so the animation is a tuple of strings built once at import — which also makes it
76
+ testable: frame count, uniform width, one head per frame, ASCII-safety.
77
+ - **Two glyph sets, chosen by probing the stream encoding.** A cp1252 Windows console
78
+ gets `O o .`; anything that can encode them gets `● ○ ·`. A command that did its work
79
+ and then died printing its own decoration is the worst of both outcomes.
80
+ - **`Out.animated`** is the one place tty, `--json`, `--quiet`, `--no-anim`,
81
+ `EDIFY_NO_ANIM`, `CI`, and `TERM=dumb` are decided — beside the existing
82
+ `Out.interactive`, so no call site invents a second rule.
83
+ - Decoration is never load-bearing: a painter exception disables the animation and the
84
+ command carries on. The cursor is restored in a `finally` and again at `atexit`, so
85
+ Ctrl-C never leaves a headless terminal behind.
86
+ - `--json` output is byte-identical to before, and a non-tty run emits no escape codes.
87
+
88
+ #### The fifth gate, and a way to pay
89
+
90
+ - **Three projects on the free plan** (`FREE_PROJECT_CAP`), unlimited on paid.
91
+ `projects.unlimited` joins the four existing entitlements; the tier docstring that
92
+ said "four gates, and they are the only four" now says five.
93
+ - **The ledger is a readable TSV** in `user_config_dir()`, one row per project: key,
94
+ path, first seen. It never leaves the machine — there is no telemetry, ever — so
95
+ hashing or hiding it would buy nothing and cost you the ability to read your own limit.
96
+ - **A project is keyed on its `git remote origin`**, falling back to the resolved path.
97
+ A re-clone, a second worktree, and a fresh CI checkout are one project. Keying on the
98
+ path would burn a slot every CI run.
99
+ - **It never breaks work already done.** Only a *new* project is refused. A repository
100
+ already in the ledger keeps installing, a deleted repository returns its slot the next
101
+ time anything reads the ledger, and every non-install command ignores it entirely. A
102
+ refused install leaves nothing behind — not even an empty `.edify/`.
103
+ - **`edify license projects`** lists what is using a slot, with `forget <path>` beside
104
+ it. Releasing a slot is not a support ticket.
105
+ - **`edify license`'s purchase subcommand** (removed in 0.2.0) prints the plan and the price and opens a Stripe
106
+ Payment Link in a browser — it opens a browser, it does not open a socket. Under
107
+ `--json`, `--quiet`, or with no terminal it prints the URL and stops.
108
+ `EDIFY_BUY_URL` overrides the link, which is how test mode is reached.
109
+ - **The price is one constant**, `PRO_PRICE`, so it cannot drift. It appears at a gate,
110
+ in `edify license status`, and in the two soft caps that warn rather than raise
111
+ (graph truncation, the registry cap). **Nowhere else** — no periodic reminder was
112
+ added, and that was decided rather than overlooked.
113
+ - No new exit code: the project gate raises the existing `TierRequired` (exit 7), which
114
+ already means "this needs the paid plan".
115
+ - `edify doctor`'s licence line now names the projects used.
116
+
117
+ #### The issuer
118
+
119
+ `tools/issue_license.py` refuses to sign with a zero or single-repeated-byte seed or a
120
+ small counting integer, requires a real email, defaults `--days` to a billing month plus
121
+ the seven-day grace `design/11-commercial.md` §5 specifies, prints a paste-ready customer
122
+ email, and appends an audit line to a gitignored `tools/.issued.tsv` that
123
+ `issue_license.py issued` reads back. `keygen` refuses to overwrite an existing seed
124
+ without `--force`, because doing so invalidates every licence signed with it.
125
+
126
+ There is no webhook, no Postgres, and no transactional email in this build. That is
127
+ deferred deliberately: the token format does not change when the webhook lands, so every
128
+ token issued by hand stays valid.
129
+
130
+ #### New environment variables
131
+
132
+ | variable | effect |
133
+ |---|---|
134
+ | `EDIFY_NO_ANIM` | no banner, no animation; static lines instead |
135
+ | `EDIFY_BUY_URL` | overrides the Payment Link, for Stripe test mode |
136
+
137
+
138
+ ### `edify init new` — a folder set up from zero, for whichever agent is opened
139
+
140
+ `init` and `setup` wrote `CLAUDE.md` and `.claude/`, and that was the whole install.
141
+ On a machine with Codex, Cursor, Gemini, Copilot, or Windsurf open — which is most of
142
+ them — EDIFY was installed and unreachable: the methodology existed in `.edify/` and no
143
+ runtime but one had been told where to look. The new command closes that, and asks the
144
+ questions detection cannot answer.
145
+
146
+ - **`edify init new [PATH]`.** The root is pinned where you point it (a new folder
147
+ inside an existing checkout no longer installs into the parent), the folder is created
148
+ if missing, EDIFY's own files are cleared first, and every library entry is installed.
149
+ `--keep` reinstalls without clearing; `--agents` narrows the runtimes; `--yes` and
150
+ `--no-interview` skip the questions.
151
+ - **Every runtime, from one table.** `src/edify/agents.py` is the table — instruction
152
+ file, command directory, file suffix, and format per runtime — and `host.py` writes
153
+ from it. Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Windsurf, and a
154
+ generic `AGENTS.md` row for anything else. All seven instruction files carry the same
155
+ block, so two tools open on one repository cannot be running two methodologies.
156
+ Gemini's pointers are TOML, so the generated marker is a `#` comment there and an HTML
157
+ comment everywhere else; Cursor's rule carries the `alwaysApply` header it needs to be
158
+ loaded at all. Adding a runtime is adding a row.
159
+ - **It asks first, and two of the answers change the install.** Eight short questions
160
+ before anything is written: which runtimes, what detection missed, who you are, your
161
+ role, what is being built, what done looks like, how much to explain, and what an
162
+ agent must never do here. The runtimes answer decides what gets installed and the
163
+ stack answer reaches the library selection, so the interview is not a survey. The rest
164
+ is written to `.edify/profile.md`, which every instruction file points at, recorded in
165
+ the ledger under a new `answered` origin that `upgrade` will never overwrite, and
166
+ read back on a re-run so last time's answers are the defaults. Enter skips any
167
+ question. With no terminal nothing is asked, no profile is written, and the full
168
+ install happens anyway — a question is never load-bearing.
169
+ - **Clearing is one implementation, not two.** `setup --fresh` and `init new` both call
170
+ `host.clear`, which walks every runtime's directories and every instruction file. A
171
+ pointer without EDIFY's marker is somebody's own file and is never touched; the block
172
+ is removed from an instruction file somebody else owns, and the file itself only goes
173
+ when nothing but the block was in it.
174
+ - **A later `edify init` keeps every runtime current.** With no `--agents`, the runtimes
175
+ are whichever ones are already set up in the folder, falling back to `--host` when
176
+ none are. Five stale instruction files and one current one is worse than either state.
177
+ A hand-written `AGENTS.md` is never taken as evidence that Codex or Cursor is set up
178
+ here, so `init` does not start writing into `.codex/` in a repository that asked for
179
+ neither. `edify skills sync` follows the same rule, and `edify doctor` now checks
180
+ every instruction file on disk rather than `CLAUDE.md` alone.
181
+
182
+ ### `/harvest` picks its own source, and the pipeline runs end to end
183
+
184
+ `/harvest` was written and could not complete a run. Three reasons, and the first one
185
+ made the other two unreachable.
186
+
187
+ - **`edify/harvest/sources.md` had no sources.** One placeholder row, `| — | — | — |`,
188
+ which the parser correctly discarded — so `edify harvest pick` printed "no sources
189
+ listed" and step ① had nothing to fetch. The table now carries six real rows with
190
+ their licence verified at the repository rather than inferred from a README badge,
191
+ including two rows that are there to be *refused* correctly: `anthropics/skills` has
192
+ no root LICENSE and per-directory terms, and `awesome-claude-code` is CC BY-NC-ND,
193
+ which is neither allowlisted nor adaptable and is therefore an `index` row — read for
194
+ links, never staged.
195
+ - **Nothing chose a row.** `pick` printed the whole table and left selection to the
196
+ caller, which meant the one decision in the pipeline computable from files was a
197
+ model's mood. `pick` now scores every row against the ledger — licence posture,
198
+ admitted-to-rejected ratio at the human door, archived status, ledger exhaustion,
199
+ months since the last draw — and names one, with the arithmetic printed and
200
+ `--source NAME` to override. Two new columns feed it: `fetch`, so gathering is a
201
+ listing instead of a search, and `status`, without which rows sharing a licence tie
202
+ and the alphabetical tie-break hands the run an archived upstream. The parse is by
203
+ column name, so an older table still reads.
204
+ - **Admission did not install.** `admit` copied the rewrite into `edify/skills/` — the
205
+ authored tree that ships — and stopped, leaving an entry that was admitted and could
206
+ not be loaded by anything. It now installs, indexes, mirrors, and re-records
207
+ governance in the same command, on the far side of the door where it belongs.
208
+
209
+ The skill file names the fetch mechanics it had left implicit (pin the commit, resolve
210
+ the licence per artifact, `curl` for bytes rather than WebFetch — staging a model's
211
+ summary of a candidate poisons the hash the ledger identifies it by) and says what to do
212
+ about the commonest quarantine, which is a candidate that *quotes* the anti-pattern the
213
+ scan looks for.
214
+
215
+ ### Installed skills are visible to the host runtime
216
+
217
+ An entry under `.edify/skills/` was installed as far as `edify skills list` was
218
+ concerned and invisible in the session the person was typing into, because Claude Code
219
+ discovers skills at `.claude/skills/<name>/SKILL.md`, one directory each.
220
+
221
+ - **`edify skills sync`**, and the same mirror inside `init`, `upgrade`, `setup`,
222
+ `skills add`, and admission. Each file is a pointer carrying the two fields the
223
+ runtime discovers on — `name` and the entry's own `description`, which is what
224
+ relevance is matched against — plus the `role · phase · tech` coordinate, and then the
225
+ canonical path. A copy would go stale the first time an entry changed.
226
+ - No `--force`: a pointer is derived output, so one that is out of date is brought
227
+ current, and one EDIFY did not write is never touched. Every generated file carries a
228
+ marker, which is how a hand-authored `SKILL.md` stays out of both the mirror and the
229
+ governance ledger.
230
+ - Governance records the mirror as `generated`, and only where the marker is present —
231
+ so `verify` no longer reports our own output as unrecorded, nor claims authorship of
232
+ a command file somebody else wrote.
233
+
234
+ ### `edify setup [PATH] [--fresh]` — the whole harness, in one folder
235
+
236
+ `init` finds its root by walking upward, so `mkdir service && cd service && edify init`
237
+ inside an existing checkout installs into the **parent**, silently, into the `.edify/`
238
+ the outer repository already has. `setup` pins the root at exactly the path given,
239
+ creates the folder if it is missing, and installs everything with force on.
240
+
241
+ `--fresh` clears EDIFY's own surface first — `.edify/`, the marked host pointers, and
242
+ its block in `CLAUDE.md` — and nothing else, ever: source code, a hand-written
243
+ `SKILL.md`, a custom command, and the rest of somebody's `CLAUDE.md` all survive it. It
244
+ is a reinstall, not `rm -rf`.
245
+
246
+ ### `/harvest` — public capability becomes a library entry
247
+
248
+ `10-harvest.md` was designed and not written. It is written now, as one skill with
249
+ four steps and one door, and the door does not open by itself.
250
+
251
+ - `.claude/skills/harvest/SKILL.md` and `/harvest` — the method a model follows:
252
+ gather, screen, rewrite, propose, stop. The contract is deliberately **not** in
253
+ `.edify/commands/`, because harvest runs in EDIFY's own repository and is never
254
+ installed into a client's. `edify harvest` refuses anywhere without the authored
255
+ `edify/harvest/` tree, so the boundary is checkable rather than documented.
256
+ - `edify harvest pick | stage | screen | propose | admit | reject | status`. The
257
+ first four run unattended; `admit` requires a person at a terminal and there is
258
+ no flag that changes that. Fetching stays outside the CLI — `stage` records what
259
+ arrived, so `edify` still opens no socket except `upgrade`.
260
+ - **`harvest/ledger.json`** — every candidate ever seen, and what became of it. A
261
+ candidate is recognised by three independent identities: its URL, the sha256 of
262
+ its raw bytes, and the entry name it would take. Any one matching is a match,
263
+ because the same file moves between repositories, gets re-tagged, and arrives
264
+ renamed. Nothing is gathered, screened, or proposed twice, and the reason
265
+ recorded against a rejection is what makes the next run cheap.
266
+ - The screen is mechanical and fail-closed: a permissive-licence allowlist where
267
+ unresolvable means `NONE-FOUND` and `NONE-FOUND` is rejected, a duplicate check
268
+ by name and by hash, and an injection scan for exfiltration, tool abuse, gate
269
+ evasion, and hidden characters. An injection hit sends the candidate to
270
+ `harvest/quarantine/` flagged rather than to the bin — someone will want to know
271
+ what was attempted. Nothing short-circuits; every failure is reported.
272
+ - `staging/` and `quarantine/` are in `.gitignore`. They hold a stranger's text
273
+ verbatim; the permanent record is the ledger's verdict and three hashes.
274
+
275
+ ### Fixed
276
+
277
+ - A `→` or `·` in command output no longer kills the command on a Windows console
278
+ that defaults to cp1252. `edify skills add` and every other line that carried one
279
+ did its work and then died writing the sentence about it — the file on disk, the
280
+ exit code saying failure. Unencodable characters now degrade to a replacement.
281
+
282
+ ### Governance over every installed file
283
+
284
+ - `.edify/governance.tsv` — one row for every file EDIFY writes into a repository:
285
+ path, kind, origin, provenance, licence, sha256, and the version that installed
286
+ it. Skill entries carried provenance already; command files, format examples, the
287
+ seeded registry, the scraped conventions, the host pointers, and `CLAUDE.md` did
288
+ not. Written by `init`, `upgrade`, and `skills add`.
289
+ - `edify governance list | verify | rebuild`, and a governance line in `edify doctor`.
290
+ - `verify` distinguishes a file EDIFY owns being **modified** — `upgrade` will
291
+ replace it — from a file the repository owns being **edited**, which is what
292
+ `mcp.md` and `conventions.md` are for. It prints; `--exit-code` makes it a gate
293
+ the customer owns, the same posture as `edify check`.
294
+ - The graph is deliberately outside the ledger: regenerated output with its own
295
+ checksums in `.edify/graph/meta`.
296
+
297
+ ### The library asks before it installs
298
+
299
+ - `edify init` shows the entries your stack matched and takes an answer, because a
300
+ skill file is trusted instruction in every matching session. `--skills
301
+ ask|all|none|<names>` and `--yes` state the answer up front.
302
+ - `edify upgrade` asks the same question about entries arriving from an archive.
303
+ - **With no terminal nothing is asked** and the whole matched set is installed, so
304
+ CI, a pipe, and a model calling the binary behave exactly as before. `CI`,
305
+ `EDIFY_ASSUME_YES`, and `EDIFY_NO_PROMPT` also switch the question off.
306
+
307
+ ### Feedback, with no telemetry added
308
+
309
+ - `edify feedback` asks four questions and writes the answers to a file under the
310
+ user's config directory, then prints the `gh` command and the URL that would send
311
+ it. **Nothing is transmitted**; `edify upgrade` remains the only command that
312
+ opens a socket, and `design/11-commercial.md` §10 is unchanged.
313
+ - A one-line invitation on stderr as the CLI opens: at most once per released
314
+ version, only on a real terminal, never in CI or a pipe. `edify feedback off`, or
315
+ `EDIFY_NO_FEEDBACK`, ends it permanently.
316
+ - `edify feedback list | show | off | on`.
317
+
318
+ ### macOS
319
+
320
+ - The config directory follows the platform: `~/Library/Application Support/edify`
321
+ on macOS, `%APPDATA%\edify` on Windows, `$XDG_CONFIG_HOME/edify` elsewhere. A Mac
322
+ that already has `~/.config/edify` keeps it — an upgrade never orphans a licence.
323
+ - The walk ignores what macOS writes into a source tree: `.DS_Store`, `__MACOSX`,
324
+ and bundle directories (`.app`, `.framework`, `.dSYM`, `.xcassets`, `.lproj`).
325
+ - `INSTALL.md` — pipx, uv, and Homebrew, with the PATH fixes people actually hit.
326
+ - `packaging/homebrew/edify.rb` — the tap formula, reviewed alongside the code it
327
+ installs.
328
+ - CI installs and drives the built wheel on macOS as well as Linux, and runs the
329
+ `pipx` path a Mac user is told to use.
330
+
331
+ ### Publishing
332
+
333
+ - `PUBLISHING.md` — registering the name, PyPI trusted publishing via GitHub OIDC,
334
+ the TestPyPI rehearsal, the per-release checklist, and the Homebrew tap.
335
+ - `.github/workflows/release.yml` — tag-driven, no API tokens, refuses to publish
336
+ when the git tag and the package version disagree, and smoke-installs the wheel on
337
+ macOS, Linux, and Windows before it uploads anything.
338
+ - The version is asserted identical in `src/edify/__init__.py`, `pyproject.toml`, and
339
+ `edify/manifest.md`.
340
+
341
+ ## [0.1.0] — 2026-08-07
342
+
343
+ First release. The graph commands and the methodology surface — steps 1 and 2 of the
344
+ build order in `design/architecture/09-cli.md` §5 — plus the install path a stranger
345
+ needs.
346
+
347
+ ### The map
348
+
349
+ - `edify graph build` — deterministic extraction over the whole tree. A rebuild on
350
+ unchanged source is byte-identical, so a graph diff is a structural diff.
351
+ - `edify graph update <dir>...` — directory-scoped re-extraction, merged into the
352
+ existing graph. This is what runs after each build phase.
353
+ - `edify graph where | dependents | defines | overlap | references | stat`.
354
+ - Python is parsed with a real syntax tree; 19 other languages are covered by a
355
+ declarative line scanner; Markdown headings and SQL tables are structural.
356
+ `meta.method_<language>` records which, so a scan is never mistaken for a parse.
357
+ - An uncovered language produces a file node and nothing else, and
358
+ `meta.languages_uncovered` names it. No model writes the graph at any stage.
359
+ - Optional adapter for an external syntax-tree extractor: `--extractor ctags`.
360
+
361
+ ### The documents
362
+
363
+ - `edify check` — the whole validation story, over specs, plans, tasks, skill files
364
+ and the server registry. It reports; it never blocks. `--exit-code` is there so a
365
+ team that needs a hard block can own one.
366
+ - `edify check --fix` — the two mechanical repairs only: resolving a filename to a
367
+ line range through the graph, and re-sorting the skill index.
368
+ - Parsers for `spec.md`, `plan.md`, `tasks.md`, skill frontmatter, and `mcp.md`.
369
+
370
+ ### The install
371
+
372
+ - `edify init` — detect the stack, extract the graph, scrape conventions from the
373
+ config files with zero model calls, install the matching skill entries, seed the
374
+ server registry, and write a fifteen-line `CLAUDE.md`. Merges into an existing
375
+ instruction file; never overwrites it.
376
+ - `edify skills list | resolve | index | add` — resolution is a lookup over a sorted
377
+ TSV, never a model reading a directory.
378
+ - `edify mcp list | check | for` — scoping per role and phase is inspectable.
379
+ - `edify doctor` — five checks and a green/amber/red line.
380
+ - `edify upgrade` — the one command that reaches the network, with `--archive` for
381
+ air-gapped machines. Every entry is validated and licence-checked before it lands.
382
+
383
+ ### The methodology tree
384
+
385
+ - Five command files: `/spec`, `/plan`, `/tasks`, `/build`, `/verify`.
386
+ - Three format contracts and their three worked examples.
387
+ - Twelve skill entries across all six roles, every one under budget.
388
+ - The harvest design, its two reference files, and the default one-entry registry.
389
+
390
+ ### Commercial
391
+
392
+ - Offline licence verification: Ed25519 in pure Python over the standard library,
393
+ checked against the RFC 8032 §7.1 test vector. No network call, no activation
394
+ server, no machine binding.
395
+ - `edify license status | activate | deactivate`.
396
+ - Free plan: everything, forever, no account, up to 25,000 graph nodes. Four paid
397
+ entitlements — `graph.unlimited`, `library.upgrade`, `mcp.multi`, `team`.
398
+ - `tools/issue_license.py` — the issuer, so the whole path is testable end to end.
399
+ - Full commercial design in `design/11-commercial.md`.
400
+
401
+ ### Known limits
402
+
403
+ - The built-in extractor scans rather than parses everything except Python,
404
+ Markdown and SQL. `edify doctor` reports this as amber and names the fix.
405
+ - `edify mcp check` cannot verify a pin for a server with a remote transport or one
406
+ that does not answer `--version`. It reports that as unprobeable rather than as
407
+ passing.
408
+ - Standalone binaries are not built yet (M4 in `design/11-commercial.md` §2). The
409
+ install path today is `pipx` or `uv tool`.
@@ -0,0 +1,242 @@
1
+ # Installing EDIFY
2
+
3
+ `edify` is a single Python package with **no dependencies**. It installs on macOS,
4
+ Linux, and Windows the same way, needs no compiler, no network at run time, and no
5
+ procurement conversation about a runtime it drags in behind it.
6
+
7
+ Requirements: **Python 3.10 or newer**. That is the whole list.
8
+
9
+ ---
10
+
11
+ ## macOS
12
+
13
+ ### With pipx (recommended)
14
+
15
+ `pipx` puts the binary on your PATH in its own virtual environment, so `edify` never
16
+ collides with a project's dependencies.
17
+
18
+ ```bash
19
+ brew install pipx # or: python3 -m pip install --user pipx
20
+ pipx ensurepath # adds ~/.local/bin to PATH; open a new shell after this
21
+ pipx install edify-agents-cli
22
+
23
+ edify version
24
+ ```
25
+
26
+ ### With uv
27
+
28
+ ```bash
29
+ brew install uv
30
+ uv tool install edify-agents-cli
31
+ ```
32
+
33
+ ### With Homebrew directly
34
+
35
+ ```bash
36
+ brew install edify-dev/tap/edify
37
+ ```
38
+
39
+ The tap installs the same PyPI artifact, wrapped in Homebrew's own Python
40
+ virtualenv.
41
+
42
+ ### If `edify: command not found`
43
+
44
+ The package installed but its directory is not on your PATH. Almost always one of:
45
+
46
+ | shell | file | line to add |
47
+ |---|---|---|
48
+ | zsh (the macOS default) | `~/.zshrc` | `export PATH="$HOME/.local/bin:$PATH"` |
49
+ | bash | `~/.bash_profile` | `export PATH="$HOME/.local/bin:$PATH"` |
50
+ | fish | `~/.config/fish/config.fish` | `fish_add_path ~/.local/bin` |
51
+
52
+ `pipx ensurepath` writes that line for you; you still have to open a new shell.
53
+
54
+ On Apple Silicon, Homebrew lives in `/opt/homebrew` rather than `/usr/local`. If
55
+ `brew` itself works but the tools it installs do not, `eval "$(/opt/homebrew/bin/brew shellenv)"`
56
+ in your shell profile is the missing piece.
57
+
58
+ ### Where macOS keeps EDIFY's own files
59
+
60
+ ```
61
+ ~/Library/Application Support/edify/license the licence token, if you have one
62
+ ~/Library/Application Support/edify/state run count and whether the feedback line is on
63
+ ~/Library/Application Support/edify/feedback/ anything `edify feedback` wrote, unsent
64
+ ```
65
+
66
+ Nothing else on the machine is touched, and nothing outside a repository is written
67
+ by a non-interactive run. A machine that already has `~/.config/edify` from an older
68
+ install keeps using it — upgrading never orphans a licence. `EDIFY_HOME` overrides
69
+ the location entirely.
70
+
71
+ ### Apple's quarantine
72
+
73
+ Not applicable. There is no downloaded binary and no code signature to check: `pip`,
74
+ `pipx`, `uv`, and `brew` all install a Python package from PyPI over TLS, and
75
+ Gatekeeper does not gate that.
76
+
77
+ ---
78
+
79
+ ## Linux
80
+
81
+ ```bash
82
+ pipx install edify-agents-cli # or: uv tool install edify-agents-cli
83
+ ```
84
+
85
+ Configuration lives in `$XDG_CONFIG_HOME/edify`, or `~/.config/edify`.
86
+
87
+ ## Windows
88
+
89
+ ```powershell
90
+ py -m pip install --user pipx
91
+ py -m pipx ensurepath
92
+ pipx install edify-agents-cli
93
+ ```
94
+
95
+ Configuration lives in `%APPDATA%\edify`.
96
+
97
+ ---
98
+
99
+ ## Verifying the install
100
+
101
+ ```bash
102
+ cd your-repository
103
+ edify init
104
+ edify doctor
105
+ ```
106
+
107
+ `doctor` prints a line per subsystem and a green/amber/red verdict. **Amber is a
108
+ normal result**: with no Universal Ctags on the machine, the built-in extractor
109
+ parses Python exactly and scans everything else, and `doctor` says so rather than
110
+ implying parse-grade coverage it does not have.
111
+
112
+ Optional, for parse-grade extraction across the rest of your stack:
113
+
114
+ ```bash
115
+ brew install universal-ctags # macOS
116
+ sudo apt install universal-ctags # Debian/Ubuntu
117
+ edify graph build --extractor ctags
118
+ ```
119
+
120
+ ## What `init` asks
121
+
122
+ One question: which entries from the agent library to install. They become trusted
123
+ instruction in every matching session, so you see the list before any of it lands.
124
+
125
+ With no terminal — CI, a pipe, a model calling the binary — nothing is asked and the
126
+ whole stack-matched set is installed. To state the answer up front:
127
+
128
+ ```bash
129
+ edify init --yes # the whole matched set, no question
130
+ edify init --skills none # none of it; add entries later
131
+ edify init --skills planner,verifier # exactly these
132
+ ```
133
+
134
+ ## Setting a folder up from zero, for every agent
135
+
136
+ `edify init` writes `CLAUDE.md` and `.claude/`. If your team also has Codex, Cursor,
137
+ Gemini, Copilot, or Windsurf open, that install is invisible to them. `edify init new`
138
+ pins the root where you point it, creates the folder if it is missing, clears EDIFY's
139
+ own files first, installs every library entry, and writes the instruction file and
140
+ command pointers each runtime actually reads.
141
+
142
+ ```bash
143
+ edify init new ./service # ask, then install for every runtime
144
+ edify init new . --agents claude,cursor
145
+ edify init new . --yes # ask nothing, install everything
146
+ ```
147
+
148
+ It asks eight short questions before installing anything — which runtimes, what stack
149
+ detection missed, who you are, your role, what is being built, what done looks like, how
150
+ much an agent should explain, and what it must never do here. Enter skips any of them.
151
+ The answers land in `.edify/profile.md`, which every instruction file points at and
152
+ which is yours to edit; a re-run offers them back as the defaults. With no terminal
153
+ nothing is asked and no profile is written.
154
+
155
+ ## Installing from a checkout
156
+
157
+ ```bash
158
+ git clone https://github.com/EDIFY-agents/EDIFY
159
+ cd EDIFY
160
+ python3 -m venv .venv && source .venv/bin/activate
161
+ pip install -e ".[dev]"
162
+ pytest -q
163
+ ```
164
+
165
+ `EDIFY_ASSETS` points the asset resolver at a checkout's `edify/` directory if you
166
+ need to run an installed binary against an edited methodology tree.
167
+
168
+ ## Updating from a checkout
169
+
170
+ `edify upgrade` pulls a newer **skill library**. `edify self update` replaces the
171
+ **CLI itself** — the two are different things and neither does the other's job.
172
+
173
+ ```bash
174
+ edify self where # which edify is this, and where did it come from
175
+ edify self update --dry-run # the exact install command, run nothing
176
+ edify self update # reinstall from the checkout this code came from
177
+ edify self update --from ~/src/edify --editable
178
+ ```
179
+
180
+ `self update` shells out to whichever tool put `edify` on PATH — uv, pipx, or pip —
181
+ because only that tool can correctly replace it. A hardcoded `pip install` into a uv
182
+ tool environment produces a second, shadowed copy, which is the worst possible outcome
183
+ for a command named "update". Detection reads `sys.prefix`; when it is wrong,
184
+ `--manager uv|pipx|pip` overrides it, and `edify self where` prints what was detected
185
+ before anything is installed. After a successful install the *new* binary is asked for
186
+ its version, so a shadowed copy shows up as a version that did not move.
187
+
188
+ `--editable` installs in place, so later edits to the checkout need no reinstall at all.
189
+
190
+ **This is one of the two commands that can reach the network.** Building a wheel from a
191
+ checkout fetches `hatchling` unless it is already cached. `--offline` is the opt-in that
192
+ refuses to reach out and fails cleanly instead.
193
+
194
+ **On Windows the running `edify.exe` may be locked** by the shell you typed into.
195
+ `self update` detects that failure and prints the exact command to run from another
196
+ shell rather than reporting a success it did not have.
197
+
198
+ `self update` never touches `.edify/` in any repository. Reinstalling the harness into a
199
+ checkout is `edify setup . --fresh`.
200
+
201
+ ## The public edition, and what a licence adds
202
+
203
+ Nothing here needs an account. The public edition, `edify-agents-cli`, is MIT-licensed
204
+ and free: every command, every query, every check, the whole methodology tree, on a
205
+ repository of any size, in as many repositories as you like. It has no caps except one —
206
+ the MCP registry scopes a single server into spawns.
207
+
208
+ The team edition, `edify-agents-teams`, is by licence. A team or partner licence adds the
209
+ team commands and lifts the one-server rule. `partner` plans are free for University of
210
+ Toronto design teams and researchers. There is no payment and no price anywhere; a
211
+ licence is issued on request.
212
+
213
+ ```bash
214
+ edify license status # which edition this machine runs, and what a licence adds
215
+ edify license activate <token> # the token you were sent
216
+ ```
217
+
218
+ Activation writes a signed token to a file and verifies it locally — there is no
219
+ activation server and no phone-home, so a licence works on an air-gapped machine and
220
+ keeps working if we are down.
221
+
222
+ `EDIFY_LICENSE` carries a token in CI without writing a file. `EDIFY_LICENSE_PUBKEY`
223
+ points verification at a self-hosted issuer. `EDIFY_HOME` moves the licence and the
224
+ feedback file together — which is also how a test isolates both.
225
+
226
+ ## Uninstalling
227
+
228
+ ```bash
229
+ pipx uninstall edify-agents-cli # or: brew uninstall edify
230
+ rm -rf ~/Library/Application\ Support/edify # macOS; ~/.config/edify elsewhere
231
+ ```
232
+
233
+ Inside a repository, EDIFY's footprint is `.edify/`, `specs/`, one command directory per
234
+ agent runtime it was asked for (`.claude/`, `.codex/`, `.cursor/`, `.gemini/`,
235
+ `.github/prompts/`, `.windsurf/`), and a marked block inside each runtime's instruction
236
+ file. `edify governance list` prints every file it put there, so removing it is a list
237
+ you can read rather than a hunt — and every generated file carries a marker line, so a
238
+ skill, prompt, or command you wrote yourself is not in that list and is not touched by
239
+ removing EDIFY.
240
+
241
+ To reinstall the lot in place rather than remove it, `edify setup . --fresh` or
242
+ `edify init new .` clears exactly that footprint and writes it again.