ez2-aib 0.1.0__tar.gz

ez2_aib-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

ez2_aib-0.1.0/NOTICE

@@ -0,0 +1,4 @@
+aib
+Copyright 2024-2026 Ez2 | 一極圖
+
+This product includes software developed by Ez2.

ez2_aib-0.1.0/PKG-INFO

@@ -0,0 +1,302 @@
+Metadata-Version: 2.4
+Name: ez2-aib
+Version: 0.1.0
+Summary: Run only the tests your change affects; ship only when nothing new is red.
+License-Expression: Apache-2.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+[English](README.md) | [繁體中文](README.zh-TW.md)
+
+# aib
+
+**Many AIs, one workspace: bring in AI tools from any vendor for free, give every seat its own persona, expertise and
+project memory, and let any AI pick up where another left off — even after a sudden disconnect.**
+
+- **Bring in any vendor's AI, free.** aib is free and open source<sup>[1]</sup>. AI coding tools<sup>[2]</sup>,
+  models you reach with an API key<sup>[3]</sup><sup>[4]</sup> and desktop AI apps (Claude, Codex Desktop, …)
+  all open as seats<sup>[5]</sup> that work together. Each AI uses your own account or key; aib charges nothing on top.
+- **Every aib has its own cockpit<sup>[6]</sup>; every cockpit has its own seats.** A cockpit is one tmux<sup>[7]</sup> window
+  with several AI seats side by side, each with a role (`dev`, `qa`, `pm`, …). Seats message each other and hand work around.
+- **Every AI has its own persona and expertise.** Each seat can have its own persona<sup>[8]</sup> (the first brain:
+  personality, tone, working principles) and its own expertise (development, testing, planning, …).
+- **More than one answer: AIs from different vendors check each other.** Give the same question to AIs from different
+  vendors; each answers, then they review each other and point out weak spots and blind spots — you are not stuck with
+  a single vendor's view.
+- **Write to the second brain<sup>[9]</sup> any time.** In the middle of building or discussing, save key points and
+  decisions to the second brain (project memory) whenever you like. Disconnects and crashes lose nothing; when an AI
+  gets muddled after a long chat, just reopen the seat and its memory comes right back.
+- **Any AI can take over.** A seat can run on Claude today and Codex tomorrow and keep the same persona and memory;
+  when a conversation fills up, it leaves a hand-off note for whoever comes next.
+- **Keep valuable conversations, fewer AI hallucinations<sup>[10]</sup>.** Points worth keeping from a conversation are
+  distilled<sup>[11]</sup> into candidates for the persona and memory, and written in once you approve them. With facts
+  written down to check, the AI guesses less from vague recall.
+- **Everything stays on your machine.** Seat records, hand-off notes, personas and project memory all live on your own
+  machine (`~/.ez2-aib/`<sup>[12]</sup>) and are never uploaded.
+
+The cockpit runs on macOS with tmux. Many AIs on one codebase means many changes, so aib also ships a safety net
+that works on its own too (Linux or macOS):
+
+- `aib test` re-runs only the tests<sup>[13]</sup> a change affects (Python, bash and Node<sup>[14]</sup> are traced); the rest
+  reuse their last **green**<sup>[15]</sup> result. Red results are never reused, and anything aib cannot measure always runs.
+- `aib ship` is the pre-push check<sup>[16]</sup>: only a package with no new red is pushed. Releases can only be cut by a human
+  at a terminal<sup>[17]</sup>.
+
+**Notes**
+- [1] Open source: the code is public; anyone may read, use and change it.
+- [2] AI coding tools: coding assistants from each vendor — Claude Code (Anthropic), Codex (OpenAI), Antigravity (Google), GitHub Copilot (GitHub), Grok (xAI) and others.
+- [3] API key: a secret string an AI service gives you, so a program can call that service on your behalf.
+- [4] Models reached with an API key: for example DeepSeek, OpenRouter (one entry point to many models) and NVIDIA.
+- [5] Seat: one AI's place in the cockpit — one AI per seat, with its own role and memory.
+- [6] Cockpit: the workspace aib opens, with several seats side by side.
+- [7] tmux: a tool that splits one terminal window into panes and keeps them running after you close the window.
+- [8] Persona: the seat's personality, tone and working principles, saved as a persona card and loaded whichever AI opens the seat.
+- [9] Second brain: the seat's project memory — a set of notes kept on your own machine.
+- [10] AI hallucination: an AI stating something incorrect as if it were true.
+- [11] Distill: pick the points worth keeping out of a conversation and turn them into rules or knowledge.
+- [12] `~/.ez2-aib/`: a folder in your home folder where aib keeps its records.
+- [13] Tests: small programs that automatically check that the code still works.
+- [14] Python, bash, Node: three common programming languages / runtimes.
+- [15] Green / red: a passing test is green, a failing one is red.
+- [16] Pre-push check: running the affected tests before pushing code to the shared version (the main branch).
+- [17] Terminal: the window where you type text commands (the Terminal app on macOS).
+
+## Quick start
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/ez2app/ez2-aib/main/install.sh | bash
+# macOS: installs into ~/ez2-aib; run the same line again any time to update
+aib update                                          # same thing, once aib is installed (aib update --tools also offers AI CLIs)
+# other ways: pipx install git+https://github.com/ez2app/ez2-aib
+#             git clone https://github.com/ez2app/ez2-aib ~/ez2-aib && export PATH="$HOME/ez2-aib/bin:$PATH"
+
+cd your-project
+aib claude safe dev                  # open a Claude Code seat named dev (it asks before every action)
+aib codex safe qa                    # and a Codex seat named qa next to it
+aib test tests/test_something.py     # first run: runs and records
+aib test tests/test_something.py     # nothing changed: reused
+aib test --all                       # the whole suite, same rules
+aib ship package --branch my-branch  # pre-push check, then push to main
+```
+
+Python<sup>[18]</sup> 3.9+ on Linux or macOS; the cockpit needs macOS and tmux. Windows is not supported (WSL2<sup>[19]</sup> is untested).
+The first line is the one-line install<sup>[20]</sup>; the other ways use pipx<sup>[21]</sup>, git<sup>[22]</sup> and PATH<sup>[23]</sup>.
+
+**Notes**
+- [18] Python: a programming language; aib is written in it, so it must be installed first.
+- [19] WSL2: a Windows feature that runs Linux inside Windows.
+- [20] One-line install: `curl … | bash` downloads the installer and runs it right away.
+- [21] pipx: a tool that installs Python command-line tools, each kept apart from the others.
+- [22] git: the tool that records every change to the code; `git clone` downloads a whole copy.
+- [23] PATH: the list of folders your computer searches for commands; adding a folder lets you type `aib`.
+
+## The cockpit: several AIs side by side
+
+The **cockpit** runs several AI coding assistants ("seats") side by side in one tmux window, each with a
+role (`dev`, `qa`, `pm`, …), a left / center / right layout, mouse menus, seat-to-seat messages, hand-off notes when a
+conversation fills up, and fleet tools<sup>[24]</sup> (seat identity, dispatch, patrol).
+
+```sh
+aib claude safe dev        # open a Claude Code seat named dev, asking before every action
+aib codex dgrs qa          # open a Codex seat named qa in allow-all mode (see below)
+aib --help-cockpit         # every option
+```
+
+- **Requirements:** macOS and tmux. Each AI's own command-line tool<sup>[25]</sup> must already be installed and logged in
+  (`claude`, `codex`, `grok`, …); aib does not install or log in for you. The cockpit has not been tried on Linux yet.
+- **bash tests on macOS:** aib traces bash scripts with bash 4.1 or newer. macOS ships bash 3.2, so tests that run bash scripts
+  are reported as "not measured" and always rerun (safe, just slower). `brew install bash`<sup>[26]</sup> makes them reusable.
+- **Permission modes, per seat:** `safe` keeps the AI tool's normal protections (it asks before editing files or running
+  commands). `dgrs` turns those protections off **for that seat only**, so the AI acts without asking; aib prints a
+  warning with the command to reopen the seat in `safe`. You choose for each seat when you open it.
+- **Claude** is a trademark of Anthropic; Codex of OpenAI; Grok of xAI. aib is not affiliated with them.
+
+**Notes**
+- [24] Fleet tools: features for managing many seats at once — who each seat is, handing out work, regular patrols.
+- [25] Command-line tool: a program you use by typing commands in a terminal (for example `claude`, `codex`).
+- [26] `brew install bash`: installs a newer bash with Homebrew, the usual way to install software on macOS.
+
+## Planned: across machines and social channels
+
+> These are planned and not usable yet; each will be listed in the CHANGELOG<sup>[27]</sup> when it lands.
+
+- **AIs on different machines talk to each other.** No need to cram every AI onto one computer: AI seats at home, at
+  work or on a cloud host<sup>[28]</sup> can message each other.
+- **Operate another machine's aib from your own.** From the aib on your computer, run another machine's aib cockpit
+  through conversation, or send commands to the aib on that host.
+- **Social conversation management.** Bring conversations from LINE, Telegram and other social platforms in and manage
+  them; LINE and Telegram already work in internal testing and will open up later.
+
+**Notes**
+- [27] CHANGELOG: the record of what each version added or changed.
+- [28] Host: a computer that runs programs — your laptop, an office machine, or a rented cloud server.
+
+## In development: faster tests
+
+> This part is still being developed; the numbers and behavior below may change.
+
+aib remembers which files every test read; next time it reruns only the tests a change affects and reuses the last green
+result for the rest.
+
+**Measured: our own development of aib** (2026-10-08 to 10-10, 28 pushes<sup>[29]</sup>, about 1,020 tests each)
+
+| How the tests run | Total for 28 pushes | Average per push | Saved vs. one at a time |
+|---|---|---|---|
+| Without aib, one test at a time<sup>[30]</sup> | 91.1 hours (about 3.8 days<sup>[31]</sup>) | 195 minutes | (baseline) 91.1 hours |
+| With aib, same project in a single run<sup>[32]</sup> | 43.8 hours (about 1.8 days) | 94 minutes | saves 47.3 hours (about 2 days, 52%) |
+| **With aib, same project split into 3 parts** | **16.6 hours (about 0.7 days)** | **36 minutes** | **saves 74.5 hours (about 3.1 days)** |
+
+- From 91.1 to 43.8 hours is aib's reuse<sup>[33]</sup>: tests a change does not affect are not run again; down to 16.6 hours comes from splitting the remaining tests into 3 parts that run at once.
+- 36 minutes is the average over these 28 pushes; once records built up, the last 10 pushes averaged about 18 minutes.
+- Is reuse ever wrong? 13 randomly chosen reused tests were really rerun: all 13 gave the same result, 0 were wrongly reused.
+
+**Expected savings per month**<sup>[34]</sup>
+
+| How the tests run | About per month | Saved vs. one at a time |
+|---|---|---|
+| Without aib, one test at a time | 395 hours (about 16.4 days) | (baseline) 395 hours |
+| With aib, same project in a single run | 190 hours (about 7.9 days) | saves 205 hours (about 8.5 days) |
+| **With aib, same project split into 3 parts** | **72 hours (about 3 days)** | **saves 323 hours (about 13.5 days)** |
+
+**Small projects (Linux, 4 cores)**
+
+| Project | pytest<sup>[35]</sup> in parallel | aib, first run | Saved on each later run |
+|---|---|---|---|
+| [attrs](https://github.com/python-attrs/attrs)<sup>[36]</sup> (26 tests) | 8.2 s | 15.1 s | about 5 s (3.0 s when nothing changed) |
+| [click](https://github.com/pallets/click)<sup>[37]</sup> (43 tests) | 6.2 s | 17.2 s | about 2 s (3.8 s when nothing changed) |
+
+- The first run records which files each test read, so it is slower than pytest; from the second run on, unaffected tests are reused.
+- "Saved on each later run" assumes nothing changed; the more files a change touches, the more tests rerun and the less is saved.
+- **Good fit:** a suite that takes minutes or more, where each change touches only part of it. **Poor fit:** a suite that finishes in a few seconds.
+- A side effect: each test runs on its own, which exposes tests that only pass after another test ran first.
+
+**Notes**
+- [29] Push: sending your finished changes to the version everyone shares.
+- [30] One test at a time: 91.1 hours is an estimate that adds up each test's time measured under aib, including tracing overhead, so it runs high.
+- [31] Day: counted as 24 hours (an AI can run around the clock).
+- [32] Single run: aib runs only the affected tests, one after another; 43.8 hours is the sum of those tests' actual run times.
+- [33] Reused: none of the files the test read changed, so its last green result is used instead of running it again.
+- [34] Expected savings per month: projected from the measured pace (about 28 pushes a week, about 121 a month) × 52 ÷ 12; fewer pushes save less. Each push saves about 160 minutes compared with one at a time, about 101 of them from aib's reuse.
+- [35] pytest: the most common Python testing tool; it runs all tests and reports which passed. "In parallel" runs several processes at once, its fastest mode.
+- [36] attrs: a well-known open-source Python package that saves programmers from writing repetitive code.
+- [37] click: a well-known open-source Python package for building command-line tools.
+
+## Languages
+
+Python (unittest<sup>[38]</sup>, pytest) is traced in full. Node (node:test, jest, mocha<sup>[39]</sup>), Go and PHP<sup>[40]</sup>
+run through aib and get the pre-push check; how much can be reused depends on what the tracer sees — see
+`docs/AIB-TEST-QUICKSTART.md` for the current table.
+Other languages can declare their test command in `.aib/ship.toml`; they always run, but packaging and releases work.
+
+**Notes**
+- [38] unittest: Python's built-in testing tool.
+- [39] node:test, jest, mocha: three common testing tools for Node.
+- [40] Go, PHP: two more programming languages.
+
+## How safe is reuse?
+
+- Only green results are reused, and only when every input the test read is byte-identical.
+- If aib cannot see what a test read (a subprocess<sup>[41]</sup> it cannot trace, network, a known native extension that reads
+  files itself), the test is marked unmeasurable and always runs.
+- **Known gap:** a C extension<sup>[42]</sup> that is *not* on aib's list and reads files from C code is invisible to Python's
+  audit hooks<sup>[43]</sup>. On Linux the native safety net below catches this; **without it (macOS, or no C compiler<sup>[44]</sup>)
+  a change to such a file may not trigger a rerun.** If your tests depend on files read that way, run `aib test --fresh`
+  before releasing.
+- `aib ship audit` re-runs a random sample of reused tests and compares.
+
+**Notes**
+- [41] Subprocess: a program that another running program starts.
+- [42] C extension: a piece written in C that Python calls; it is fast, but Python cannot see the files it reads.
+- [43] Audit hooks: Python's built-in "tell me when a file is opened" mechanism, which aib uses to record what tests read.
+- [44] C compiler: the tool that turns C source code into a runnable program (for example `cc`, `gcc`, `clang`).
+
+## Privacy
+
+aib never sends your code, test results or anything else to us. Its records stay on your machine
+(`~/.ez2-aib/`, plus a small cache in `~/.cache/ez2-aib/`). aib's own network traffic is what `aib ship` does with git:
+fetch from and push to **your own** remote<sup>[45]</sup>.
+
+The cockpit is different in one way: the AI seats you open are the AI vendors' own tools, and they talk to their vendors
+as they always do. What the cockpit itself keeps on your machine, all under `~/.ez2-aib/`:
+seat records and hand-off notes, seat-to-seat messages, project and role cards, and API keys you add for API-key seats
+(in `~/.ez2-aib/secrets/`, folder 0700 / files 0600<sup>[46]</sup>, encrypted with a key stored next to them — this stops casual reading
+and accidental commits, not someone who can already read your home folder). Delete `~/.ez2-aib/` to remove all of it.
+
+**Notes**
+- [45] Remote (fetch / push): the copy of the code kept online (for example on GitHub); fetch downloads from it, push uploads to it.
+- [46] 0700 / 0600: file permissions meaning only your own account can read and write.
+
+## The native safety net (Linux only)
+
+Some tests read files from C code (a native extension, a C library), which Python's audit hooks cannot see.
+On Linux, if a C compiler (`cc`, `gcc` or `clang`) is on your PATH, aib compiles a small C file that ships with it
+(`aib/tools/verify/ldp-shim/`) into `~/.cache/ez2-aib/` and preloads it (`LD_PRELOAD`<sup>[47]</sup>) **into test processes only**,
+so those reads are recorded too. Without a compiler, or if the library cannot be loaded, the safety net stays off and
+aib says why. **Then the gap described above is open:** reads done in C code go unrecorded, so a change to such a file
+may not make its tests rerun. It is never available on macOS.
+Turn it off with `AIB_NATIVE_GUARD=0`.
+
+**Notes**
+- [47] `LD_PRELOAD`: a Linux feature that loads a small piece into a program when it starts; aib uses it to record reads done in C.
+
+## Keeping the temp folder clean
+
+Tests often leave temp files behind, and sometimes background programs (a tmux server a test forgot to stop can run for
+hours and eat gigabytes of memory). aib cleans up after the tests it runs:
+
+- Each test gets its own temp folder (`TMPDIR`<sup>[48]</sup>, under `<tmp>/aibt-…`), deleted when the test ends.
+- Background programs a test started and left running are stopped when it ends.
+- The summary names the tests that left something behind, so you can fix them at the source.
+- `aib tmp` lists what aib and its tests left in the temp folder and any leftover background programs from tests that
+  already finished; `aib tmp --apply` removes them. It never touches anything that is not aib's, symbolic links, or
+  anything a running program still uses. `aib ship` does this automatically before the pre-push check.
+
+**Notes**
+- [48] `TMPDIR`: the setting that tells programs where to put temporary files.
+
+## CI
+
+`aib ship ci` writes a GitHub Actions<sup>[49]</sup> workflow<sup>[50]</sup> that keeps aib's records in the Actions cache, so CI<sup>[51]</sup>
+runs only what changed too. Pull requests<sup>[52]</sup> from forks<sup>[53]</sup> always run everything (they must not be able to touch the records).
+
+**Notes**
+- [49] GitHub Actions: GitHub's automation service; push code and it runs your tests automatically.
+- [50] Workflow: the settings file for GitHub Actions that lists the steps to run.
+- [51] CI (continuous integration): running the tests in the cloud automatically every time someone pushes code.
+- [52] Pull request (PR): a request asking the project owner to merge your changes.
+- [53] Fork: someone's own copy of your project under their account.
+
+## Uninstall
+
+```sh
+rm -rf ~/ez2-aib ~/.local/bin/aib        # if you used the one-line install
+pipx uninstall ez2-aib                   # if you installed it with pipx
+rm -rf ~/.ez2-aib ~/.cache/ez2-aib       # aib's records and cache (outside your project aib writes only these, plus temporary files in the system temp folder)
+rm -rf your-project/.aib                 # only if `aib ship` created it and you no longer want it
+```
+
+## Contributing and security
+
+See `CONTRIBUTING.md` and `SECURITY.md`.
+
+## Why local first
+
+If all development depends on a remote host or an online platform, everything stops the moment it goes down or
+cannot be reached. aib was born out of exactly that: we moved development off online platforms and back onto our own
+computers, so records, memory and work in progress stay on the local machine and keep going when something remote fails.
+
+The AIs themselves still connect to their vendors' services, but seat records, personas and memory live on your
+computer — switch to another vendor's AI, or wait for the network to come back, and pick up right where you left off.
+
+## History
+
+AIB is the successor to **ACB**, which we started developing in 2024.
+ACB's architecture no longer fit the way it is used today, so instead of patching it further we rebuilt it from the ground up as AIB.
+`aib test` and `aib ship` are the open-source core of that rebuild.
+
+## License
+
+Apache License 2.0 — see `LICENSE`.