aicontexts 0.1.0__tar.gz

aicontexts-0.1.0/LICENSE

@@ -0,0 +1,18 @@
+MIT No Attribution
+
+Copyright 2026 Wayne C. Gramlich
+
+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.
+
+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.

aicontexts-0.1.0/PKG-INFO

@@ -0,0 +1,327 @@
+Metadata-Version: 2.4
+Name: aicontexts
+Version: 0.1.0
+Summary: Startup context for AI sessions: tasks, issues and rules that the AI loads
+Author: Wayne C. Gramlich
+License-Expression: MIT-0
+Project-URL: Homepage, https://github.com/waynegramlich/aicontexts
+Project-URL: Issues, https://github.com/waynegramlich/aicontexts/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# AI Contexts: Startup Context for AI Sessions
+
+The `ai_contexts` program manages the context that an AI loads at session
+start time.  The context is broken into 3 broad categories:
+
+* **Tasks:**
+  Tasks are chunks of work, such as a feature to add or a cleanup to do.
+* **Issues:**
+  Issues include code bugs, feature requests, documentation, testing, etc.
+  Dealing with an issue may require multiple tasks.
+* **Rules:**
+  Rules are instructions that an AI follows in every session, such as
+  version control or coding rules, which may be shared by several projects.
+  They are discussed in the section about Rules much further below.
+
+With `ai_contexts`, you can easily switch your AI's context each time you
+change your development focus, so that it loads only what is relevant.
+This keeps the AI from being distracted by unrelated work and saves both time
+and money.
+
+Using `ai_contexts` is simple.  You write a few lines describing a task, and
+the AI does the bookkeeping.  While the task is open, it keeps its working notes
+in the task's directory, and when the task is done, it writes a short
+summary and closes it.  From then on, only that summary is loaded, so a
+long-running project keeps its history without the AI having to wade
+through it.
+
+## Getting Started
+
+The installation of `ai_contexts` is covered in "Installation" near the
+end of this document.
+
+Each category is a collection of Items that lives in its own directory
+(e.g. `TASKS/`, `ISSUES/` and `RULES/`).  A project can have other collections
+as well (e.g. `IDEAS/`), as long as their names start with a unique letter.
+
+These directories are manipulated by the `aic` command (which is
+a symbolic link to the `ai_contexts.py` program).  For example:
+
+* `aic TASKS create` creates the `TASKS/` directory.
+* `aic ISSUES create` creates the `ISSUES/` directory.
+
+Each one asks before creating the directory, and marks it as a collection
+with a hidden `.ai_contexts.json` file inside it.  It also writes
+`AI_Contexts_Rules.md` into the directory, which teaches the AI how to use
+`aic`.
+
+Next, tell the AI about them.  For Claude Code, add these two lines to
+the project's `CLAUDE.md` file:
+
+```
+@TASKS/AI_Contexts_Rules.md
+@TASKS/Startup.md
+```
+
+`aic` rewrites both files every time it runs, so they always exist and
+are always up to date: `AI_Contexts_Rules.md` matches the version of
+`aic` you have, and `TASKS/Startup.md` loads the context of your tasks
+and issues.  (Every collection gets its own copy of
+`AI_Contexts_Rules.md`, so you can import it from whichever collection
+you have; import just one, so that it is not loaded twice.)  `aic` also
+warns you about any `@` import in `CLAUDE.md` whose file does not exist.
+
+To create a task, give it a number and a title:
+
+```
+aic TASKS create 1 Write the README
+```
+
+This creates the `TASKS/1_Write_the_README/` sub-directory.  The first
+task is always number `1`, since numbers never have gaps (see below).
+
+To see the tasks, run `aic TASKS ls`, which shows:
+
+```
+1  Pending    T.wr  Write the README
+```
+
+What you see is:
+
+* **`1`**: This is the task number.
+  (It can be hierarchical; see shortly below.)
+* **`Pending`**: This is the initial task state.
+* **`T.wr`**: This is the task tag.  It is constructed by taking the
+  first letter of the collection name (i.e. `TASKS`) followed by a
+  period.  The rest is constructed by taking the title (see next item),
+  dropping the words "a", "an", "of" and "the", and concatenating the
+  first letter of each remaining word in lower case.  For example,
+  "Write the README" drops "the", leaving **W**rite **R**EADME, so the
+  tag is `T.wr`.
+* **`Write the README`**: The full title is listed last.
+
+Collection and command names can both be shortened to any unique
+prefix, in any case, so `aic t ls` works as well, and `aic t op T.wr` is
+short for `aic TASKS open T.wr`.  (If a prefix is ambiguous, such as `c`
+for `close` or `create`, `aic` lists the choices.)  Tags can not be
+shortened, so `T.wr` must be typed in full (though `t.wr` works too).
+`aic` also works from anywhere inside the project: it looks for the
+collections in the current directory, and then in each parent directory
+in turn, stopping at the top of a git or Mercurial repository.
+
+Numbers are hierarchical, so a task can be broken into smaller ones:
+
+```
+aic t create 1.1 Draft the introduction
+aic t create 2 Publish the README
+```
+
+Then `aic TASKS ls` lists:
+
+```
+1    Pending    T.wr  Write the README
+1.1  Pending    T.di  Draft the introduction
+2    Pending    T.pr  Publish the README
+```
+
+Hierarchical numbers:
+
+* A hierarchical number is a sequence of positive integers separated by `.`
+  (e.g. `1.3.2`.)
+* They can be sorted, but they are never allowed to have gaps.
+  Thus, task `1.3` can only be created after `1.1` and `1.2` exist.
+* They change as tasks are added, moved, inserted and deleted.  This is
+  why tags are typically used instead of hierarchical numbers.
+* Text (and the AI) refers to a task by its tag followed by `~` and its
+  number at the time, such as `T.di~1.1`, so that its directory is easy
+  to find.  The number is never updated afterwards, so it records what
+  the number was when the text was written.  `aic` ignores the `~1.1`,
+  so `aic t open T.di~1.1` works too.
+
+## Context Files
+
+Each created sub-directory contains the following 4 files:
+
+* **`Details.md`**:
+  This file is entirely edited by the User.  It provides the description
+  of the Task/Issue.  For a Task it describes the goal of the task.  For
+  an Issue, it describes the Issue, but not necessarily how to fix it.
+* **`Summary.md`**:
+  This is a file where the AI stores the context it needs once the
+  Task/Issue is closed.
+* **`Context.md`**:
+  This file is where the AI stores the context it needs when working on it.
+  It is allowed to be quite detailed.  However, the AI only sees the context
+  when the task or issue is in the Open (or Reference) state.
+* **`.item.json`**:
+  This is a hidden file entirely managed by `aic` to keep track of things.
+
+At AI startup, the AI is directed to read at most 2 of the 3 files
+above:
+
+* **`Details.md`**: This is read until the Task/Issue is closed.
+* **`Context.md`**: This is read while the Task/Issue is open.
+* **`Summary.md`**: This is read once the Task/Issue is closed.
+
+Thus, the AI gets the context it needs to focus on individual Tasks
+and/or Issues.
+
+Prior to working on a task, first enter its details into `Details.md`,
+then open it:
+
+```
+aic t open T.wr
+```
+
+The next AI session loads its `Details.md` and `Context.md`.  When the
+work is done, ask the AI to close the task: it writes the `Summary.md`
+and it runs the `aic t close T.wr` command for you.  In practice, you rarely
+run `aic` yourself once the collections exist; you ask the AI to create,
+open and close tasks and issues, and it runs the commands.
+
+## States
+
+A task (or issue) is always in one of these states:
+
+* **Pending:** Not started yet.  Every new task starts out Pending.
+* **Open:** Being worked on.  Its `Context.md` is loaded.
+* **Reference:** Not being worked on, but its `Context.md` is still
+  loaded, so its notes stay available.
+* **Suspended:** Put aside for now.
+* **Closed:** Done.  Only its `Summary.md` is loaded.
+* **Rejected:** Decided against.  It is treated like a Closed one.
+
+The commands are named after the states (`pending`, `open`, `reference`,
+`suspend`, `close` and `reject`), e.g. `aic t close T.wr`.  `aic t ls`
+leaves out Closed and Rejected tasks; `aic t ls -a` lists them all.
+
+## Moving Things Around
+
+* `aic t move T.di after 2` moves a task (and its children), and
+  `aic t create before 1 Outline the README` creates one in front of
+  another; the other tasks are renumbered to make room or close the gap.
+* `aic t rename T.di to Draft the overview` changes a title.  If that
+  changes the tag, `ai_contexts` offers to update the `.md` files that
+  use the old one, in the collections and directly in the project
+  directory (it suggests a `grep` command for anywhere else).
+* `aic t transfer T.di issues` moves a task that turns out to be an issue
+  into `ISSUES/`, where its tag becomes `I.di`.
+* `aic t delete T.di` deletes a task for good.
+
+There is no undo, so keep the collections in a version control system.
+Before a move, rename or transfer, if there has not been one for over an
+hour, `ai_contexts` suggests taking a snapshot (e.g. `git commit`) first.
+
+## Priorities
+
+Issues can be given a priority once it is enabled for the collection
+(`aic i enable priority`): 0 (catastrophic), 1 (high), 2 (medium) or 3
+(low), set with `aic i priority I.dbzib 1`.  `aic i ls` then lists the
+issues by priority first.
+
+## Other Conveniences
+
+* A tag can stand in for its collection: `aic I.dbzib close` is the same
+  as `aic ISSUES close I.dbzib`.
+* `aic T.wr show` shows everything about a task.
+* `aic` with no arguments lists the collections, and `aic -h` lists all
+  of the commands.
+* Every command checks the collections and tells you about anything that
+  needs fixing (such as a title edited by hand), and how to fix it.
+
+## Rules Collections
+
+A rules collection (e.g. `RULES/`) holds rules that the AI should load at
+the start of every session, such as version control or coding rules
+shared by several projects.  Each rule is a file that can live anywhere,
+and `ai_contexts` keeps a read-only copy of it in the project, as the
+rule's `Details.md` (the AI may not import a file from outside the
+project without approval):
+
+The easiest way to get rules is to copy them from another project:
+
+```
+aic RULES create
+aic r copy ../other_project/RULES
+```
+
+A collection named `RULES` is a rules collection from the start.  (A
+rules collection with another name is made with `aic NAME create`, and
+then `aic n type rules` while it is still empty.)
+x
+`aic r copy` lists the other project's rules by number and title, and
+asks which to copy:
+
+```
+Rules in ../other_project/RULES:
+1  Code Marker Rules
+2  Python Coding Rules
+3  Version Control Rules
+Copy which? (e.g. 1,3-5; empty for none) 2-3
+1  InActive   R.pcr  Python Coding Rules
+2  InActive   R.vcr  Version Control Rules
+To use them: ai_contexts RULES activate 1-2
+```
+
+The choices are numbers and ranges, separated by commas or spaces, and
+can also be given on the command line (`aic r copy ../other_project/RULES
+2-3`).  A rule you already have is marked `(have it)` and is not copied
+again.  The directory can also be any directory of rule files (e.g.
+`../shared_rules/`), and a single file becomes a rule with `aic r create
+1 ../shared_rules/Version_Control_Rules.md`.  Either way, the rule's file
+is its source, and `aic` keeps the copy up to date with it.
+
+`aic` refuses to make a rule from a `CLAUDE.md` file, and asks before
+using a file that looks like it is about the project (like `README.md`)
+or that imports other files.
+
+A new rule is InActive until it is activated.  Every time `ai_contexts`
+runs, it refreshes the copies from their source files and rewrites
+`RULES/Active_Rules.md` to import the Active ones, so adding this line to
+`CLAUDE.md` loads them:
+
+```
+@RULES/Active_Rules.md
+```
+
+## Installation
+
+`ai_contexts` is a single Python program, `ai_contexts.py`, that needs
+Python 3.11 or later and nothing beyond the standard library.  Nothing
+else needs to be installed: the rules it gives the AI are built in.  To install
+it:
+
+1. Install the `aicontexts` package from PyPI, which gives you both the
+   `ai_contexts` and `aic` commands.  With `uv` or `pipx`, it gets an
+   environment of its own:
+
+   ```
+   uv tool install aicontexts
+   pipx install aicontexts
+   ```
+
+   Or, without either, copy `ai_contexts.py` into a directory on your
+   `PATH`, and make a symbolic link to it named `aic`:
+
+   ```
+   cp ai_contexts.py ~/bin/
+   ln -s ai_contexts.py ~/bin/aic
+   ```
+
+2. Check it with `aic --test`, which runs its tests in a temporary
+   directory.
+
+3. Create the collections and set up `CLAUDE.md` as described in
+   "Getting Started".
+
+`REFERENCE.md` has the details of how `ai_contexts` works.

aicontexts-0.1.0/README.md

@@ -0,0 +1,307 @@
+# AI Contexts: Startup Context for AI Sessions
+
+The `ai_contexts` program manages the context that an AI loads at session
+start time.  The context is broken into 3 broad categories:
+
+* **Tasks:**
+  Tasks are chunks of work, such as a feature to add or a cleanup to do.
+* **Issues:**
+  Issues include code bugs, feature requests, documentation, testing, etc.
+  Dealing with an issue may require multiple tasks.
+* **Rules:**
+  Rules are instructions that an AI follows in every session, such as
+  version control or coding rules, which may be shared by several projects.
+  They are discussed in the section about Rules much further below.
+
+With `ai_contexts`, you can easily switch your AI's context each time you
+change your development focus, so that it loads only what is relevant.
+This keeps the AI from being distracted by unrelated work and saves both time
+and money.
+
+Using `ai_contexts` is simple.  You write a few lines describing a task, and
+the AI does the bookkeeping.  While the task is open, it keeps its working notes
+in the task's directory, and when the task is done, it writes a short
+summary and closes it.  From then on, only that summary is loaded, so a
+long-running project keeps its history without the AI having to wade
+through it.
+
+## Getting Started
+
+The installation of `ai_contexts` is covered in "Installation" near the
+end of this document.
+
+Each category is a collection of Items that lives in its own directory
+(e.g. `TASKS/`, `ISSUES/` and `RULES/`).  A project can have other collections
+as well (e.g. `IDEAS/`), as long as their names start with a unique letter.
+
+These directories are manipulated by the `aic` command (which is
+a symbolic link to the `ai_contexts.py` program).  For example:
+
+* `aic TASKS create` creates the `TASKS/` directory.
+* `aic ISSUES create` creates the `ISSUES/` directory.
+
+Each one asks before creating the directory, and marks it as a collection
+with a hidden `.ai_contexts.json` file inside it.  It also writes
+`AI_Contexts_Rules.md` into the directory, which teaches the AI how to use
+`aic`.
+
+Next, tell the AI about them.  For Claude Code, add these two lines to
+the project's `CLAUDE.md` file:
+
+```
+@TASKS/AI_Contexts_Rules.md
+@TASKS/Startup.md
+```
+
+`aic` rewrites both files every time it runs, so they always exist and
+are always up to date: `AI_Contexts_Rules.md` matches the version of
+`aic` you have, and `TASKS/Startup.md` loads the context of your tasks
+and issues.  (Every collection gets its own copy of
+`AI_Contexts_Rules.md`, so you can import it from whichever collection
+you have; import just one, so that it is not loaded twice.)  `aic` also
+warns you about any `@` import in `CLAUDE.md` whose file does not exist.
+
+To create a task, give it a number and a title:
+
+```
+aic TASKS create 1 Write the README
+```
+
+This creates the `TASKS/1_Write_the_README/` sub-directory.  The first
+task is always number `1`, since numbers never have gaps (see below).
+
+To see the tasks, run `aic TASKS ls`, which shows:
+
+```
+1  Pending    T.wr  Write the README
+```
+
+What you see is:
+
+* **`1`**: This is the task number.
+  (It can be hierarchical; see shortly below.)
+* **`Pending`**: This is the initial task state.
+* **`T.wr`**: This is the task tag.  It is constructed by taking the
+  first letter of the collection name (i.e. `TASKS`) followed by a
+  period.  The rest is constructed by taking the title (see next item),
+  dropping the words "a", "an", "of" and "the", and concatenating the
+  first letter of each remaining word in lower case.  For example,
+  "Write the README" drops "the", leaving **W**rite **R**EADME, so the
+  tag is `T.wr`.
+* **`Write the README`**: The full title is listed last.
+
+Collection and command names can both be shortened to any unique
+prefix, in any case, so `aic t ls` works as well, and `aic t op T.wr` is
+short for `aic TASKS open T.wr`.  (If a prefix is ambiguous, such as `c`
+for `close` or `create`, `aic` lists the choices.)  Tags can not be
+shortened, so `T.wr` must be typed in full (though `t.wr` works too).
+`aic` also works from anywhere inside the project: it looks for the
+collections in the current directory, and then in each parent directory
+in turn, stopping at the top of a git or Mercurial repository.
+
+Numbers are hierarchical, so a task can be broken into smaller ones:
+
+```
+aic t create 1.1 Draft the introduction
+aic t create 2 Publish the README
+```
+
+Then `aic TASKS ls` lists:
+
+```
+1    Pending    T.wr  Write the README
+1.1  Pending    T.di  Draft the introduction
+2    Pending    T.pr  Publish the README
+```
+
+Hierarchical numbers:
+
+* A hierarchical number is a sequence of positive integers separated by `.`
+  (e.g. `1.3.2`.)
+* They can be sorted, but they are never allowed to have gaps.
+  Thus, task `1.3` can only be created after `1.1` and `1.2` exist.
+* They change as tasks are added, moved, inserted and deleted.  This is
+  why tags are typically used instead of hierarchical numbers.
+* Text (and the AI) refers to a task by its tag followed by `~` and its
+  number at the time, such as `T.di~1.1`, so that its directory is easy
+  to find.  The number is never updated afterwards, so it records what
+  the number was when the text was written.  `aic` ignores the `~1.1`,
+  so `aic t open T.di~1.1` works too.
+
+## Context Files
+
+Each created sub-directory contains the following 4 files:
+
+* **`Details.md`**:
+  This file is entirely edited by the User.  It provides the description
+  of the Task/Issue.  For a Task it describes the goal of the task.  For
+  an Issue, it describes the Issue, but not necessarily how to fix it.
+* **`Summary.md`**:
+  This is a file where the AI stores the context it needs once the
+  Task/Issue is closed.
+* **`Context.md`**:
+  This file is where the AI stores the context it needs when working on it.
+  It is allowed to be quite detailed.  However, the AI only sees the context
+  when the task or issue is in the Open (or Reference) state.
+* **`.item.json`**:
+  This is a hidden file entirely managed by `aic` to keep track of things.
+
+At AI startup, the AI is directed to read at most 2 of the 3 files
+above:
+
+* **`Details.md`**: This is read until the Task/Issue is closed.
+* **`Context.md`**: This is read while the Task/Issue is open.
+* **`Summary.md`**: This is read once the Task/Issue is closed.
+
+Thus, the AI gets the context it needs to focus on individual Tasks
+and/or Issues.
+
+Prior to working on a task, first enter its details into `Details.md`,
+then open it:
+
+```
+aic t open T.wr
+```
+
+The next AI session loads its `Details.md` and `Context.md`.  When the
+work is done, ask the AI to close the task: it writes the `Summary.md`
+and it runs the `aic t close T.wr` command for you.  In practice, you rarely
+run `aic` yourself once the collections exist; you ask the AI to create,
+open and close tasks and issues, and it runs the commands.
+
+## States
+
+A task (or issue) is always in one of these states:
+
+* **Pending:** Not started yet.  Every new task starts out Pending.
+* **Open:** Being worked on.  Its `Context.md` is loaded.
+* **Reference:** Not being worked on, but its `Context.md` is still
+  loaded, so its notes stay available.
+* **Suspended:** Put aside for now.
+* **Closed:** Done.  Only its `Summary.md` is loaded.
+* **Rejected:** Decided against.  It is treated like a Closed one.
+
+The commands are named after the states (`pending`, `open`, `reference`,
+`suspend`, `close` and `reject`), e.g. `aic t close T.wr`.  `aic t ls`
+leaves out Closed and Rejected tasks; `aic t ls -a` lists them all.
+
+## Moving Things Around
+
+* `aic t move T.di after 2` moves a task (and its children), and
+  `aic t create before 1 Outline the README` creates one in front of
+  another; the other tasks are renumbered to make room or close the gap.
+* `aic t rename T.di to Draft the overview` changes a title.  If that
+  changes the tag, `ai_contexts` offers to update the `.md` files that
+  use the old one, in the collections and directly in the project
+  directory (it suggests a `grep` command for anywhere else).
+* `aic t transfer T.di issues` moves a task that turns out to be an issue
+  into `ISSUES/`, where its tag becomes `I.di`.
+* `aic t delete T.di` deletes a task for good.
+
+There is no undo, so keep the collections in a version control system.
+Before a move, rename or transfer, if there has not been one for over an
+hour, `ai_contexts` suggests taking a snapshot (e.g. `git commit`) first.
+
+## Priorities
+
+Issues can be given a priority once it is enabled for the collection
+(`aic i enable priority`): 0 (catastrophic), 1 (high), 2 (medium) or 3
+(low), set with `aic i priority I.dbzib 1`.  `aic i ls` then lists the
+issues by priority first.
+
+## Other Conveniences
+
+* A tag can stand in for its collection: `aic I.dbzib close` is the same
+  as `aic ISSUES close I.dbzib`.
+* `aic T.wr show` shows everything about a task.
+* `aic` with no arguments lists the collections, and `aic -h` lists all
+  of the commands.
+* Every command checks the collections and tells you about anything that
+  needs fixing (such as a title edited by hand), and how to fix it.
+
+## Rules Collections
+
+A rules collection (e.g. `RULES/`) holds rules that the AI should load at
+the start of every session, such as version control or coding rules
+shared by several projects.  Each rule is a file that can live anywhere,
+and `ai_contexts` keeps a read-only copy of it in the project, as the
+rule's `Details.md` (the AI may not import a file from outside the
+project without approval):
+
+The easiest way to get rules is to copy them from another project:
+
+```
+aic RULES create
+aic r copy ../other_project/RULES
+```
+
+A collection named `RULES` is a rules collection from the start.  (A
+rules collection with another name is made with `aic NAME create`, and
+then `aic n type rules` while it is still empty.)
+x
+`aic r copy` lists the other project's rules by number and title, and
+asks which to copy:
+
+```
+Rules in ../other_project/RULES:
+1  Code Marker Rules
+2  Python Coding Rules
+3  Version Control Rules
+Copy which? (e.g. 1,3-5; empty for none) 2-3
+1  InActive   R.pcr  Python Coding Rules
+2  InActive   R.vcr  Version Control Rules
+To use them: ai_contexts RULES activate 1-2
+```
+
+The choices are numbers and ranges, separated by commas or spaces, and
+can also be given on the command line (`aic r copy ../other_project/RULES
+2-3`).  A rule you already have is marked `(have it)` and is not copied
+again.  The directory can also be any directory of rule files (e.g.
+`../shared_rules/`), and a single file becomes a rule with `aic r create
+1 ../shared_rules/Version_Control_Rules.md`.  Either way, the rule's file
+is its source, and `aic` keeps the copy up to date with it.
+
+`aic` refuses to make a rule from a `CLAUDE.md` file, and asks before
+using a file that looks like it is about the project (like `README.md`)
+or that imports other files.
+
+A new rule is InActive until it is activated.  Every time `ai_contexts`
+runs, it refreshes the copies from their source files and rewrites
+`RULES/Active_Rules.md` to import the Active ones, so adding this line to
+`CLAUDE.md` loads them:
+
+```
+@RULES/Active_Rules.md
+```
+
+## Installation
+
+`ai_contexts` is a single Python program, `ai_contexts.py`, that needs
+Python 3.11 or later and nothing beyond the standard library.  Nothing
+else needs to be installed: the rules it gives the AI are built in.  To install
+it:
+
+1. Install the `aicontexts` package from PyPI, which gives you both the
+   `ai_contexts` and `aic` commands.  With `uv` or `pipx`, it gets an
+   environment of its own:
+
+   ```
+   uv tool install aicontexts
+   pipx install aicontexts
+   ```
+
+   Or, without either, copy `ai_contexts.py` into a directory on your
+   `PATH`, and make a symbolic link to it named `aic`:
+
+   ```
+   cp ai_contexts.py ~/bin/
+   ln -s ai_contexts.py ~/bin/aic
+   ```
+
+2. Check it with `aic --test`, which runs its tests in a temporary
+   directory.
+
+3. Create the collections and set up `CLAUDE.md` as described in
+   "Getting Started".
+
+`REFERENCE.md` has the details of how `ai_contexts` works.