chore: add exver documentation for ai agents

* add documentation for ai agents

* docs: consolidate CLAUDE.md and CONTRIBUTING.md, add style guidelines

- Refactor CLAUDE.md to reference CONTRIBUTING.md for build/test/format info
- Expand CONTRIBUTING.md with comprehensive build targets, env vars, and testing
- Add code style guidelines section with conventional commits
- Standardize SDK prettier config to use single quotes (matching web)
- Add project-level Claude Code settings to disable co-author attribution

* style(sdk): apply prettier with single quotes

Run prettier across sdk/base and sdk/package to apply the
standardized quote style (single quotes matching web).

* docs: add USER.md for per-developer TODO filtering

- Add agents/USER.md to .gitignore (contains user identifier)
- Document session startup flow in CLAUDE.md:
  - Create USER.md if missing, prompting for identifier
  - Filter TODOs by @username tags
  - Offer relevant TODOs on session start

* docs: add i18n documentation task to agent TODOs

* docs: document i18n ID patterns in core/

Add agents/i18n-patterns.md covering rust-i18n setup, translation file
format, t!() macro usage, key naming conventions, and locale selection.
Remove completed TODO item and add reference in CLAUDE.md.

* chore: clarify that all builds work on any OS with Docker

agents/exver.md

@@ -0,0 +1,301 @@
+# exver — Extended Versioning
+
+Extended semver supporting **downstream versioning** (wrapper updates independent of upstream) and **flavors** (package fork variants).
+
+Two implementations exist:
+- **Rust crate** (`exver`) — used in `core/`. Source: https://github.com/Start9Labs/exver-rs
+- **TypeScript** (`sdk/base/lib/exver/index.ts`) — used in `sdk/` and `web/`
+
+Both parse the same string format and agree on `satisfies` semantics.
+
+## Version Format
+
+An **ExtendedVersion** string looks like:
+
+```
+[#flavor:]upstream:downstream
+```
+
+- **upstream** — the original package version (semver-style: `1.2.3`, `1.2.3-beta.1`)
+- **downstream** — the StartOS wrapper version (incremented independently)
+- **flavor** — optional lowercase ASCII prefix for fork variants
+
+Examples:
+- `1.2.3:0` — upstream 1.2.3, first downstream release
+- `1.2.3:2` — upstream 1.2.3, third downstream release
+- `#bitcoin:21.0:1` — bitcoin flavor, upstream 21.0, downstream 1
+- `1.0.0-rc.1:0` — upstream with prerelease tag
+
+## Core Types
+
+### `Version`
+
+A semver-style version with arbitrary digit segments and optional prerelease.
+
+**Rust:**
+```rust
+use exver::Version;
+
+let v = Version::new([1, 2, 3], []);              // 1.2.3
+let v = Version::new([1, 0], ["beta".into()]);     // 1.0-beta
+let v: Version = "1.2.3".parse().unwrap();
+
+v.number()      // &[1, 2, 3]
+v.prerelease()  // &[]
+```
+
+**TypeScript:**
+```typescript
+const v = new Version([1, 2, 3], [])
+const v = Version.parse("1.2.3")
+
+v.number      // number[]
+v.prerelease  // (string | number)[]
+v.compare(other)        // 'greater' | 'equal' | 'less'
+v.compareForSort(other) // -1 | 0 | 1
+```
+
+Default: `0`
+
+### `ExtendedVersion`
+
+The primary version type. Wraps upstream + downstream `Version` plus an optional flavor.
+
+**Rust:**
+```rust
+use exver::ExtendedVersion;
+
+let ev = ExtendedVersion::new(
+    Version::new([1, 2, 3], []),
+    Version::default(),          // downstream = 0
+);
+let ev: ExtendedVersion = "1.2.3:0".parse().unwrap();
+
+ev.flavor()      // Option<&str>
+ev.upstream()    // &Version
+ev.downstream()  // &Version
+
+// Builder methods (consuming):
+ev.with_flavor("bitcoin")
+ev.without_flavor()
+ev.map_upstream(|v| ...)
+ev.map_downstream(|v| ...)
+```
+
+**TypeScript:**
+```typescript
+const ev = new ExtendedVersion(null, upstream, downstream)
+const ev = ExtendedVersion.parse("1.2.3:0")
+const ev = ExtendedVersion.parseEmver("1.2.3.4")  // emver compat
+
+ev.flavor      // string | null
+ev.upstream    // Version
+ev.downstream  // Version
+
+ev.compare(other)        // 'greater' | 'equal' | 'less' | null
+ev.equals(other)         // boolean
+ev.greaterThan(other)    // boolean
+ev.lessThan(other)       // boolean
+ev.incrementMajor()      // new ExtendedVersion
+ev.incrementMinor()      // new ExtendedVersion
+```
+
+**Ordering:** Versions with different flavors are **not comparable** (`PartialOrd`/`compare` returns `None`/`null`).
+
+Default: `0:0`
+
+### `VersionString` (Rust only, StartOS wrapper)
+
+Defined in `core/src/util/version.rs`. Caches the original string representation alongside the parsed `ExtendedVersion`. Used as the key type in registry version maps.
+
+```rust
+use crate::util::VersionString;
+
+let vs: VersionString = "1.2.3:0".parse().unwrap();
+let vs = VersionString::from(extended_version);
+
+// Deref to ExtendedVersion:
+vs.satisfies(&range);
+vs.upstream();
+
+// String access:
+vs.as_str();           // &str
+AsRef::<str>::as_ref(&vs);
+```
+
+`Ord` is implemented with a total ordering — versions with different flavors are ordered by flavor name (unflavored sorts last).
+
+### `VersionRange`
+
+A predicate over `ExtendedVersion`. Supports comparison operators, boolean logic, and flavor constraints.
+
+**Rust:**
+```rust
+use exver::VersionRange;
+
+// Constructors:
+VersionRange::any()                          // matches everything
+VersionRange::none()                         // matches nothing
+VersionRange::exactly(ev)                    // = ev
+VersionRange::anchor(GTE, ev)               // >= ev
+VersionRange::caret(ev)                      // ^ev (compatible changes)
+VersionRange::tilde(ev)                      // ~ev (patch-level changes)
+
+// Combinators (smart — eagerly simplify):
+VersionRange::and(a, b)                      // a && b
+VersionRange::or(a, b)                       // a || b
+VersionRange::not(a)                         // !a
+
+// Parsing:
+let r: VersionRange = ">=1.0.0:0".parse().unwrap();
+let r: VersionRange = "^1.2.3:0".parse().unwrap();
+let r: VersionRange = ">=1.0.0 <2.0.0".parse().unwrap();   // implicit AND
+let r: VersionRange = ">=1.0.0 || >=2.0.0".parse().unwrap();
+let r: VersionRange = "#bitcoin".parse().unwrap();          // flavor match
+let r: VersionRange = "*".parse().unwrap();                 // any
+
+// Monoid wrappers for folding:
+AnyRange  // fold with or, empty = None
+AllRange  // fold with and, empty = Any
+```
+
+**TypeScript:**
+```typescript
+// Constructors:
+VersionRange.any()
+VersionRange.none()
+VersionRange.anchor('=', ev)
+VersionRange.anchor('>=', ev)
+VersionRange.anchor('^', ev)                 // ^ and ~ are first-class operators
+VersionRange.anchor('~', ev)
+VersionRange.flavor(null)                    // match unflavored versions
+VersionRange.flavor("bitcoin")               // match #bitcoin versions
+
+// Combinators — static (smart, variadic):
+VersionRange.and(a, b, c, ...)
+VersionRange.or(a, b, c, ...)
+
+// Combinators — instance (not smart, just wrap):
+range.and(other)
+range.or(other)
+range.not()
+
+// Parsing:
+VersionRange.parse(">=1.0.0:0")
+VersionRange.parseEmver(">=1.2.3.4")        // emver compat
+
+// Analysis (TS only):
+range.normalize()                            // canonical form (see below)
+range.satisfiable()                          // boolean
+range.intersects(other)                      // boolean
+```
+
+**Checking satisfaction:**
+
+```rust
+// Rust:
+version.satisfies(&range)  // bool
+```
+```typescript
+// TypeScript:
+version.satisfies(range)   // boolean
+range.satisfiedBy(version) // boolean (convenience)
+```
+
+Also available on `Version` (wraps in `ExtendedVersion` with downstream=0).
+
+When no operator is specified in a range string, `^` (caret) is the default.
+
+## Operators
+
+| Syntax | Rust | TS | Meaning |
+|--------|------|----|---------|
+| `=`    | `EQ` | `'='` | Equal |
+| `!=`   | `NEQ` | `'!='` | Not equal |
+| `>`    | `GT` | `'>'` | Greater than |
+| `>=`   | `GTE` | `'>='` | Greater than or equal |
+| `<`    | `LT` | `'<'` | Less than |
+| `<=`   | `LTE` | `'<='` | Less than or equal |
+| `^`    | expanded to `And(GTE, LT)` | `'^'` | Compatible (first non-zero digit unchanged) |
+| `~`    | expanded to `And(GTE, LT)` | `'~'` | Patch-level (minor unchanged) |
+
+## Flavor Rules
+
+- Versions with **different flavors** never satisfy comparison operators (except `!=`, which returns true)
+- `VersionRange::Flavor(Some("bitcoin"))` matches only `#bitcoin:*` versions
+- `VersionRange::Flavor(None)` matches only unflavored versions
+- Flavor constraints compose with `and`/`or`/`not` like any other range
+
+## Reduction and Normalization
+
+### Rust: `reduce()` (shallow)
+
+`VersionRange::reduce(self) -> Self` re-applies smart constructor rules to one level of the AST. Useful for simplifying a node that was constructed directly (e.g. deserialized) rather than through the smart constructors.
+
+**Smart constructor rules applied by `and`, `or`, `not`, and `reduce`:**
+
+`and`:
+- `and(Any, b) → b`, `and(a, Any) → a`
+- `and(None, _) → None`, `and(_, None) → None`
+
+`or`:
+- `or(Any, _) → Any`, `or(_, Any) → Any`
+- `or(None, b) → b`, `or(a, None) → a`
+
+`not`:
+- `not(=v) → !=v`, `not(!=v) → =v`
+- `not(and(a, b)) → or(not(a), not(b))` (De Morgan)
+- `not(or(a, b)) → and(not(a), not(b))` (De Morgan)
+- `not(not(a)) → a`
+- `not(Any) → None`, `not(None) → Any`
+
+### TypeScript: `normalize()` (deep, canonical)
+
+`VersionRange.normalize(): VersionRange` in `sdk/base/lib/exver/index.ts` performs full normalization by converting the range AST into a canonical form. This is a deep operation that produces a semantically equivalent but simplified range.
+
+**How it works:**
+
+1. **`tables()`** — Converts the VersionRange AST into truth tables (`VersionRangeTable`). Each table is a number line split at version boundary points, with boolean values for each segment indicating whether versions in that segment satisfy the range. Separate tables are maintained per flavor (and for flavor negations).
+
+2. **`VersionRangeTable.zip(a, b, func)`** — Merges two tables by walking their boundary points in sorted order and applying a boolean function (`&&` or `||`) to combine segment values. Adjacent segments with the same boolean value are collapsed automatically.
+
+3. **`VersionRangeTable.and/or/not`** — Table-level boolean operations. `and` computes the cross-product of flavor tables (since `#a && #b` for different flavors is unsatisfiable). `not` inverts all segment values.
+
+4. **`VersionRangeTable.collapse()`** — Checks if a table is uniformly true or false across all flavors and segments. Returns `true`, `false`, or `null` (mixed).
+
+5. **`VersionRangeTable.minterms()`** — Converts truth tables back into a VersionRange AST in [sum-of-products](https://en.wikipedia.org/wiki/Canonical_normal_form#Minterms) canonical form. Each `true` segment becomes a product term (conjunction of boundary constraints), and all terms are joined with `or`. Adjacent boundary points collapse into `=` anchors.
+
+**Example:** `normalize` can simplify:
+- `>=1.0.0:0 && <=1.0.0:0` → `=1.0.0:0`
+- `>=2.0.0:0 || >=1.0.0:0` → `>=1.0.0:0`
+- `!(!>=1.0.0:0)` → `>=1.0.0:0`
+
+**Also exposes:**
+- `satisfiable(): boolean` — returns `true` if there exists any version satisfying the range (checks if `collapse(tables())` is not `false`)
+- `intersects(other): boolean` — returns `true` if `and(this, other)` is satisfiable
+
+## API Differences Between Rust and TypeScript
+
+| | Rust | TypeScript |
+|-|------|------------|
+| **`^` / `~`** | Expanded at construction to `And(GTE, LT)` | First-class operator on `Anchor` |
+| **`not()`** | Static, eagerly simplifies (De Morgan, double negation) | Instance method, just wraps |
+| **`and()`/`or()`** | Binary static | Both binary instance and variadic static |
+| **Normalization** | `reduce()` — shallow, one AST level | `normalize()` — deep canonical form via truth tables |
+| **Satisfiability** | Not available | `satisfiable()` and `intersects(other)` |
+| **ExtendedVersion helpers** | `with_flavor()`, `without_flavor()`, `map_upstream()`, `map_downstream()` | `incrementMajor()`, `incrementMinor()`, `greaterThan()`, `lessThan()`, `equals()`, etc. |
+| **Monoid wrappers** | `AnyRange` (fold with `or`) and `AllRange` (fold with `and`) | Not present — use variadic static methods |
+| **`VersionString`** | Wrapper caching parsed + string form | Not present |
+| **Emver compat** | `From<emver::Version>` for `ExtendedVersion` | `ExtendedVersion.parseEmver()`, `VersionRange.parseEmver()` |
+
+## Serde
+
+All types serialize/deserialize as strings (requires `serde` feature, enabled in StartOS):
+
+```json
+{
+  "version": "1.2.3:0",
+  "targetVersion": ">=1.0.0:0 <2.0.0:0",
+  "sourceVersion": "^0.3.0:0"
+}
+```

core/src/error.rs

@@ -508,8 +508,10 @@ impl From<Error> for RpcError {
 }
 impl From<RpcError> for Error {
     fn from(e: RpcError) -> Self {
+        let data = ErrorData::from(&e);
+        let info = data.info.clone();
         Error::new(
-            ErrorData::from(&e),
+            data,
             if let Ok(kind) = e.code.try_into() {
                 kind
             } else if e.code == METHOD_NOT_FOUND_ERROR.code {
@@ -523,6 +525,7 @@ impl From<RpcError> for Error {
                 ErrorKind::Unknown
             },
         )
+        .with_info(info)
     }
 }
 

core/src/install/mod.rs

@@ -137,6 +137,7 @@ pub async fn install(
             json!({
                 "id": id,
                 "targetVersion": VersionRange::exactly(version.deref().clone()),
+                "otherVersions": "none",
             }),
             RegistryUrlParams {
                 registry: registry.clone(),
@@ -484,7 +485,7 @@ pub async fn cli_install(
             let mut packages: GetPackageResponse = from_value(
                 ctx.call_remote::<RegistryContext>(
                     "package.get",
-                    json!({ "id": &id, "targetVersion": version, "sourceVersion": source_version }),
+                    json!({ "id": &id, "targetVersion": version, "sourceVersion": source_version, "otherVersions": "none" }),
                 )
                 .await?,
             )?;

core/src/registry/package/get.rs

@@ -15,6 +15,7 @@ use crate::progress::{FullProgressTracker, ProgressUnits};
 use crate::registry::context::RegistryContext;
 use crate::registry::device_info::DeviceInfo;
 use crate::registry::package::index::{PackageIndex, PackageVersionInfo};
+use crate::s9pk::manifest::LocaleString;
 use crate::s9pk::merkle_archive::source::ArchiveSource;
 use crate::s9pk::v2::SIG_CONTEXT;
 use crate::util::VersionString;
@@ -38,11 +39,11 @@ impl Default for PackageDetailLevel {
     }
 }
 
-#[derive(Debug, Deserialize, Serialize, TS)]
+#[derive(Clone, Debug, Deserialize, Serialize, TS)]
 #[serde(rename_all = "camelCase")]
 #[ts(export)]
 pub struct PackageInfoShort {
-    pub release_notes: String,
+    pub release_notes: LocaleString,
 }
 
 #[derive(Debug, Deserialize, Serialize, TS, Parser, HasModel)]
@@ -89,17 +90,20 @@ impl GetPackageResponse {
 
             let lesser_versions: BTreeMap<_, _> = self
                 .other_versions
-                .as_ref()
+                .clone()
                 .into_iter()
                 .flatten()
-                .filter(|(v, _)| ***v < *version)
+                .filter(|(v, _)| **v < *version)
                 .collect();
 
             if !lesser_versions.is_empty() {
                 table.add_row(row![bc => "OLDER VERSIONS"]);
                 table.add_row(row![bc => "VERSION", "RELEASE NOTES"]);
                 for (version, info) in lesser_versions {
-                    table.add_row(row![AsRef::<str>::as_ref(version), &info.release_notes]);
+                    table.add_row(row![
+                        AsRef::<str>::as_ref(&version),
+                        &info.release_notes.localized()
+                    ]);
                 }
             }
 
@@ -147,6 +151,7 @@ fn get_matching_models(
         id,
         source_version,
         device_info,
+        target_version,
         ..
     }: &GetPackageParams,
 ) -> Result<Vec<(PackageId, ExtendedVersion, Model<PackageVersionInfo>)>, Error> {
@@ -165,26 +170,29 @@ fn get_matching_models(
             .as_entries()?
             .into_iter()
             .map(|(v, info)| {
+                let ev = ExtendedVersion::from(v);
                 Ok::<_, Error>(
-                    if source_version.as_ref().map_or(Ok(true), |source_version| {
-                        Ok::<_, Error>(
-                            source_version.satisfies(
-                                &info
-                                    .as_source_version()
-                                    .de()?
-                                    .unwrap_or(VersionRange::any()),
-                            ),
-                        )
-                    })? {
+                    if target_version.as_ref().map_or(true, |tv| ev.satisfies(tv))
+                        && source_version.as_ref().map_or(Ok(true), |source_version| {
+                            Ok::<_, Error>(
+                                source_version.satisfies(
+                                    &info
+                                        .as_source_version()
+                                        .de()?
+                                        .unwrap_or(VersionRange::any()),
+                                ),
+                            )
+                        })?
+                    {
                         let mut info = info.clone();
                         if let Some(device_info) = &device_info {
                             if info.for_device(device_info)? {
-                                Some((k.clone(), ExtendedVersion::from(v), info))
+                                Some((k.clone(), ev, info))
                             } else {
                                 None
                             }
                         } else {
-                            Some((k.clone(), ExtendedVersion::from(v), info))
+                            Some((k.clone(), ev, info))
                         }
                     } else {
                         None
@@ -207,12 +215,7 @@ pub async fn get_package(ctx: RegistryContext, params: GetPackageParams) -> Resu
     for (id, version, info) in get_matching_models(&peek.as_index().as_package(), &params)? {
         let package_best = best.entry(id.clone()).or_default();
         let package_other = other.entry(id.clone()).or_default();
-        if params
-            .target_version
-            .as_ref()
-            .map_or(true, |v| version.satisfies(v))
-            && package_best.keys().all(|k| !(**k > version))
-        {
+        if package_best.keys().all(|k| !(**k > version)) {
             for worse_version in package_best
                 .keys()
                 .filter(|k| ***k < version)
@@ -569,3 +572,42 @@ pub async fn cli_download(
 
     Ok(())
 }
+
+#[test]
+fn check_matching_info_short() {
+    use crate::registry::package::index::PackageMetadata;
+    use crate::s9pk::manifest::{Alerts, Description};
+    use crate::util::DataUrl;
+
+    let lang_map = |s: &str| {
+        LocaleString::LanguageMap([("en".into(), s.into())].into_iter().collect())
+    };
+
+    let info = PackageVersionInfo {
+        metadata: PackageMetadata {
+            title: "Test Package".into(),
+            icon: DataUrl::from_vec("image/png", vec![]),
+            description: Description {
+                short: lang_map("A short description"),
+                long: lang_map("A longer description of the test package"),
+            },
+            release_notes: lang_map("Initial release"),
+            git_hash: None,
+            license: "MIT".into(),
+            wrapper_repo: "https://github.com/example/wrapper".parse().unwrap(),
+            upstream_repo: "https://github.com/example/upstream".parse().unwrap(),
+            support_site: "https://example.com/support".parse().unwrap(),
+            marketing_site: "https://example.com".parse().unwrap(),
+            donation_url: None,
+            docs_url: None,
+            alerts: Alerts::default(),
+            dependency_metadata: BTreeMap::new(),
+            os_version: exver::Version::new([0, 3, 6], []),
+            sdk_version: None,
+            hardware_acceleration: false,
+        },
+        source_version: None,
+        s9pks: Vec::new(),
+    };
+    from_value::<PackageInfoShort>(to_value(&info).unwrap()).unwrap();
+}

core/src/tunnel/web.rs

@@ -524,26 +524,26 @@ pub async fn init_web(ctx: CliContext) -> Result<(), Error> {
                     "To access your Web URL securely, trust your Root CA (displayed above) on your client device(s):\n",
                     "  - MacOS\n",
                     "    1. Open the Terminal app\n",
-                    "    2. Paste the following command (**DO NOTt** click Return): pbcopy < ~/Desktop/ca.crt\n",
+                    "    2. Paste the following command (**DO NOT** click Return): pbcopy < ~/Desktop/ca.crt\n",
                     "    3. Copy your Root CA (including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----)\n",
                     "    4. Back in Terminal, click Return. ca.crt is saved to your Desktop\n",
-                    "    5. Complete by trusting your Root CA: https://https://staging.docs.start9.com/device-guides/mac/ca.html\n",
+                    "    5. Complete by trusting your Root CA: https://staging.docs.start9.com/device-guides/mac/ca.html\n",
                     "  - Linux\n",
                     "    1. Open gedit, nano, or any editor\n",
                     "    2. Copy/paste your Root CA (including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----)\n",
                     "    3. Name the file ca.crt and save as plaintext\n",
-                    "    5. Complete by trusting your Root CA: https://https://staging.docs.start9.com/device-guides/linux/ca.html\n",
+                    "    5. Complete by trusting your Root CA: https://staging.docs.start9.com/device-guides/linux/ca.html\n",
                     "  - Windows\n",
                     "    1. Open the Notepad app\n",
                     "    2. Copy/paste your Root CA (including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----)\n",
                     "    3. Name the file ca.crt and save as plaintext\n",
-                    "    5. Complete by trusting your Root CA: https://https://staging.docs.start9.com/device-guides/windows/ca.html\n",
+                    "    5. Complete by trusting your Root CA: https://staging.docs.start9.com/device-guides/windows/ca.html\n",
                     "  - Android/Graphene\n",
                     "    1. Send the ca.crt file (created above) to yourself\n",
-                    "    2. Complete by trusting your Root CA: https://https://staging.docs.start9.com/device-guides/android/ca.html\n",
+                    "    2. Complete by trusting your Root CA: https://staging.docs.start9.com/device-guides/android/ca.html\n",
                     "  - iOS\n",
                     "    1. Send the ca.crt file (created above) to yourself\n",
-                    "    2. Complete by trusting your Root CA: https://https://staging.docs.start9.com/device-guides/ios/ca.html\n",
+                    "    2. Complete by trusting your Root CA: https://staging.docs.start9.com/device-guides/ios/ca.html\n",
                 ));
 
                 return Ok(());