@aimlsuperagent/agent 0.1.0 → 0.1.1

package/DEPLOYMENT_LOG.md

@@ -36,4 +36,22 @@ Commit or build: pending
 Change: Prepared package metadata for `@aimlsuperagent/agent` with restricted publish config, file allowlist, dry-run script, and private publishing documentation.
 Verification: `npm run check:release`; `npm run pack:dry-run`.
 Rollback: revert package metadata to local-only package before publishing.
-Risks: publishing remains intentionally blocked by `private:true` until npm scope ownership and private package support are confirmed.
+Risks: publishing remains blocked until npm scope ownership and private package support are confirmed.
+
+## 2026-06-01 - Marvin Freedman Repo Connection
+
+Platform: GitHub and npm package metadata
+Commit or build: pending
+Change: Cloned `github.com/marvinbfreedman/aimlsuperagent`, updated npm package metadata for `@aimlsuperagent/agent` to point repository and issue links at `marvinbfreedman/aimlsuperagent`, and kept restricted npm publishing config.
+Verification: `npm run check:release`; `npm run pack:dry-run`; `npm publish --dry-run --access restricted --cache ./.npm-cache`.
+Rollback: restore `package.json` repository and bug links to the previous repository URL and publish a new patch version if npm metadata needs to move back.
+Risks: npm package metadata changes only become visible on npm after publishing a new version.
+
+## 2026-06-01 - Trusted Publishing Workflow
+
+Platform: GitHub Actions and npm
+Commit or build: pending
+Change: Added `.github/workflows/npm-publish.yml` for npm Trusted Publishing with GitHub OIDC, `id-token: write`, Node 24, release readiness checks, and restricted npm publish.
+Verification: pending local repo check and GitHub push.
+Rollback: remove the workflow file and publish manually with npm OTP or an npm token that npm accepts for package PUT writes.
+Risks: npm package settings must trust `marvinbfreedman/aimlsuperagent` with workflow filename `npm-publish.yml` before this workflow can publish.

package/README.md

@@ -82,6 +82,7 @@ aiml-superagent/
     10-adoption-playbook.md
     11-anti-patterns.md
     12-context-budget.md
+    13-package-analytics.md
     comparison-claude-md.md
     release-checklist.md
   schemas/
@@ -105,44 +106,73 @@ aiml-superagent/
 
 ## Quick Start
 
-From this repository:
+Install the package in your project. This is the recommended setup for teams and CI because the CLI version is pinned in `package.json`:
 
 ```bash
-npm run check
+npm i -D @aimlsuperagent/agent
 ```
 
 Copy the templates into a project:
 
 ```bash
-node bin/aiml-superagent.js init ../your-project
+npx aiml-superagent init .
 ```
 
 Check a project for SuperAgent readiness:
 
 ```bash
-node bin/aiml-superagent.js check ../your-project
+npx aiml-superagent check .
+```
+
+For personal machine-wide use, install the CLI globally:
+
+```bash
+npm i -g @aimlsuperagent/agent
+aiml-superagent check .
 ```
 
 Freshly initialized projects are expected to show `needs-review` until template placeholders for project name, dates, and proof commands are replaced.
 
-Private npm package preparation:
+From this repository, maintainers can run:
 
 ```bash
+npm run check
 npm run pack:dry-run
 ```
 
 Before making a repo public:
 
 ```bash
-node bin/aiml-superagent.js check . --release
+npx aiml-superagent check . --release
 ```
 
 For CI where medium-risk findings should fail the build:
 
 ```bash
-node bin/aiml-superagent.js check . --strict
+npx aiml-superagent check . --strict
+```
+
+## Package Analytics
+
+CLI analytics is disabled by default.
+
+Enable it only when you want package usage events sent to the AiML SuperAgent tracking endpoint:
+
+```bash
+AIML_SUPERAGENT_ANALYTICS=1 aiml-superagent check .
 ```
 
+You can also enable or disable it per command:
+
+```bash
+aiml-superagent check . --analytics
+aiml-superagent check . --no-analytics
+```
+
+The package sends only privacy-safe operational metadata: command name, package version, Node major version, platform, architecture, CI flag, duration, exit code, readiness label, and finding counts. It does not send file contents, absolute paths, repo names, project names, environment variable values, credentials, or note contents. Like any HTTP request, the receiving endpoint may also receive normal request metadata such as IP address and user-agent.
+
+Use `AIML_SUPERAGENT_ANALYTICS_ENDPOINT` to point the package at a different compatible endpoint.
+
 ## The Operating Loop
 
 Every task follows the same loop:
@@ -215,7 +245,7 @@ The model can change. The operating discipline should remain stable.
 2. Fill in production owners, deployment surfaces, package manager, test commands, and secret names.
 3. Add `DEPLOYMENT_LOG.md` after the next live deploy.
 4. Add incident reports only for issues that change future behavior.
-5. Run `node bin/aiml-superagent.js check`.
+5. Run `npx aiml-superagent check`.
 6. Iterate until the checker reports no high-risk gaps.
 
 ## Design Principles
@@ -244,9 +274,9 @@ See [docs/comparison-claude-md.md](docs/comparison-claude-md.md).
 
 Private release candidate. The repository can remain private while using the MIT License; the license defines reuse terms if and when the project is shared publicly.
 
-Prepared package name: `@aimlsuperagent/agent`.
+Package name: `@aimlsuperagent/agent`.
 
-Publishing is intentionally blocked by `"private": true` until npm scope ownership and private package access are confirmed. See [docs/npm-private-publishing.md](docs/npm-private-publishing.md).
+The npm package uses restricted/private access while early testing continues. Authorized users must be added to the npm organization/team and run `npm login` before installing. See [docs/npm-private-publishing.md](docs/npm-private-publishing.md).
 
 ## License
 

package/REPO_SOURCE_OF_TRUTH.json

@@ -57,7 +57,7 @@
       "all templates are copy-safe",
       "checker passes",
       "README links resolve",
-      "npm private scope confirmed before removing private:true"
+      "npm restricted/private access confirmed before publishing"
     ]
   },
   "secrets": {

package/WORKING_NOTES.md

@@ -2,7 +2,8 @@
 
 ## Current State
 
-- Repository is private.
+- Repository is private at `github.com/marvinbfreedman/aimlsuperagent`.
+- npm package is `@aimlsuperagent/agent` and uses restricted/private package access.
 - Goal is a public-ready release candidate for AiML SuperAgent.
 - Positioning: not a replacement for behavior files, but the next operating layer after them.
 - Core differentiator: Context Minimizer, which reduces token waste by separating durable memory from active task context.
@@ -18,10 +19,11 @@
 
 ## Open Decisions
 
-- Whether to publish as a GitHub-only framework or an npm starter package.
+- Whether to make the npm package public after private-package testing is complete.
 - Whether to add model-specific adapter files for Claude, Codex, Cursor, and Gemini in separate folders.
 
 ## Decisions
 
 - License set to MIT while repository remains private. This preserves private development while preparing clean public reuse terms.
-- Package name prepared as `@aimlsuperagent/agent`, but `private:true` remains as a safety brake until npm scope ownership and private package access are confirmed.
+- Package metadata points at `github.com/marvinbfreedman/aimlsuperagent`.
+- npm scope ownership and restricted package access are confirmed for `@aimlsuperagent/agent`.

package/bin/aiml-superagent.js

@@ -74,6 +74,9 @@ const CONTEXT_SIZE_LIMITS = [
   }
 ];
 
+const DEFAULT_ANALYTICS_ENDPOINT = "https://aimlsuperagent.com/api/visitor-track";
+const DEFAULT_ANALYTICS_TIMEOUT_MS = 750;
+
 function usage() {
   console.log(`AiML SuperAgent
 
@@ -81,6 +84,10 @@ Usage:
   aiml-superagent init [target-dir]
   aiml-superagent check [target-dir] [--json] [--release] [--strict]
 
+Analytics:
+  Disabled by default. Set AIML_SUPERAGENT_ANALYTICS=1 or pass --analytics.
+  Pass --no-analytics to disable analytics for one command.
+
 Examples:
   node bin/aiml-superagent.js init ../my-app
   node bin/aiml-superagent.js check ../my-app
@@ -97,6 +104,21 @@ function readJson(file) {
   return JSON.parse(fs.readFileSync(file, "utf8"));
 }
 
+let cachedPackageVersion;
+
+function packageVersion() {
+  if (cachedPackageVersion) return cachedPackageVersion;
+
+  try {
+    const packageJson = readJson(path.join(repoRootFromScript(), "package.json"));
+    cachedPackageVersion = String(packageJson.version || "0.0.0");
+  } catch {
+    cachedPackageVersion = "0.0.0";
+  }
+
+  return cachedPackageVersion;
+}
+
 function ensureDir(dir) {
   fs.mkdirSync(dir, { recursive: true });
 }
@@ -429,7 +451,8 @@ function parseArgs(argv) {
   const options = {
     json: false,
     release: false,
-    strict: false
+    strict: false,
+    analytics: null
   };
   const positionals = [];
 
@@ -440,6 +463,10 @@ function parseArgs(argv) {
       options.release = true;
     } else if (arg === "--strict") {
       options.strict = true;
+    } else if (arg === "--analytics") {
+      options.analytics = true;
+    } else if (arg === "--no-analytics") {
+      options.analytics = false;
     } else {
       positionals.push(arg);
     }
@@ -448,30 +475,170 @@ function parseArgs(argv) {
   return { command: positionals[0], targetArg: positionals[1], options };
 }
 
-const { command, targetArg, options } = parseArgs(process.argv.slice(2));
+function isTruthy(value) {
+  return /^(1|true|yes|on)$/i.test(String(value || "").trim());
+}
 
-if (!command || command === "--help" || command === "-h") {
-  usage();
-  process.exit(0);
+function analyticsEnabled(options) {
+  if (options.analytics === true) return true;
+  if (options.analytics === false) return false;
+  return isTruthy(process.env.AIML_SUPERAGENT_ANALYTICS);
+}
+
+function analyticsEndpoint() {
+  const endpoint = String(process.env.AIML_SUPERAGENT_ANALYTICS_ENDPOINT || DEFAULT_ANALYTICS_ENDPOINT).trim();
+  return /^https?:\/\//i.test(endpoint) ? endpoint : null;
+}
+
+function analyticsTimeoutMs() {
+  const parsed = Number.parseInt(String(process.env.AIML_SUPERAGENT_ANALYTICS_TIMEOUT_MS || ""), 10);
+  if (Number.isFinite(parsed) && parsed > 0 && parsed <= 5000) return parsed;
+  return DEFAULT_ANALYTICS_TIMEOUT_MS;
+}
+
+function compactObject(object) {
+  return Object.fromEntries(
+    Object.entries(object).filter(([, value]) => value !== undefined && value !== null)
+  );
+}
+
+function isCiEnvironment() {
+  return Boolean(
+    process.env.CI ||
+      process.env.GITHUB_ACTIONS ||
+      process.env.GITLAB_CI ||
+      process.env.CIRCLECI ||
+      process.env.VERCEL ||
+      process.env.NETLIFY
+  );
 }
 
-if (command === "init") {
-  const targetDir = path.resolve(targetArg || ".");
-  const actions = copyTemplates(targetDir);
+function actionCounts(actions) {
+  const counts = {};
+
   for (const action of actions) {
-    console.log(`${action.type}: ${action.file}`);
+    counts[action.type] = (counts[action.type] || 0) + 1;
   }
-  process.exit(0);
+
+  return counts;
 }
 
-if (command === "check") {
-  const targetDir = path.resolve(targetArg || ".");
-  const result = checkProject(targetDir, options);
-  const readiness = score(result.findings);
-  printCheck(result, options.json);
-  process.exit(readiness.high > 0 || (options.strict && readiness.medium > 0) ? 1 : 0);
+async function recordCliAnalytics(options, event) {
+  if (!analyticsEnabled(options) || typeof globalThis.fetch !== "function") return;
+
+  const endpoint = analyticsEndpoint();
+  if (!endpoint) return;
+
+  const command = event.command || "unknown";
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), analyticsTimeoutMs());
+
+  const body = {
+    eventName: "package_cli_command",
+    siteName: "aimlsuperagent-package",
+    path: `/cli/${command}`,
+    title: "AiML SuperAgent CLI",
+    data: compactObject({
+      packageName: "@aimlsuperagent/agent",
+      packageVersion: packageVersion(),
+      command,
+      result: event.exitCode === 0 ? "success" : "failure",
+      exitCode: event.exitCode,
+      durationMs: event.durationMs,
+      nodeMajor: Number.parseInt(process.versions.node.split(".")[0], 10),
+      platform: process.platform,
+      arch: process.arch,
+      ci: isCiEnvironment(),
+      json: Boolean(options.json),
+      release: Boolean(options.release),
+      strict: Boolean(options.strict),
+      readiness: event.readiness?.label,
+      highFindings: event.readiness?.high,
+      mediumFindings: event.readiness?.medium,
+      lowFindings: event.readiness?.low,
+      actionCounts: event.actionCounts
+    })
+  };
+
+  try {
+    await globalThis.fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "user-agent": `aiml-superagent/${packageVersion()} node/${process.version}`
+      },
+      body: JSON.stringify(body),
+      signal: controller.signal
+    });
+  } catch {
+    // Analytics is best-effort and must never affect CLI behavior.
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function main() {
+  const startedAt = Date.now();
+  const { command, targetArg, options } = parseArgs(process.argv.slice(2));
+
+  if (!command || command === "--help" || command === "-h") {
+    usage();
+    const exitCode = 0;
+    await recordCliAnalytics(options, {
+      command: "help",
+      exitCode,
+      durationMs: Date.now() - startedAt
+    });
+    return exitCode;
+  }
+
+  if (command === "init") {
+    const targetDir = path.resolve(targetArg || ".");
+    const actions = copyTemplates(targetDir);
+    for (const action of actions) {
+      console.log(`${action.type}: ${action.file}`);
+    }
+    const exitCode = 0;
+    await recordCliAnalytics(options, {
+      command,
+      exitCode,
+      durationMs: Date.now() - startedAt,
+      actionCounts: actionCounts(actions)
+    });
+    return exitCode;
+  }
+
+  if (command === "check") {
+    const targetDir = path.resolve(targetArg || ".");
+    const result = checkProject(targetDir, options);
+    const readiness = score(result.findings);
+    printCheck(result, options.json);
+    const exitCode = readiness.high > 0 || (options.strict && readiness.medium > 0) ? 1 : 0;
+    await recordCliAnalytics(options, {
+      command,
+      exitCode,
+      durationMs: Date.now() - startedAt,
+      readiness
+    });
+    return exitCode;
+  }
+
+  console.error(`Unknown command: ${command}`);
+  usage();
+  const exitCode = 1;
+  await recordCliAnalytics(options, {
+    command: "unknown",
+    exitCode,
+    durationMs: Date.now() - startedAt
+  });
+  return exitCode;
 }
 
-console.error(`Unknown command: ${command}`);
-usage();
-process.exit(1);
+main()
+  .then((exitCode) => {
+    process.exit(exitCode);
+  })
+  .catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });

package/docs/04-verification-loop.md

@@ -77,6 +77,6 @@ node scripts/validate-schema.mjs
 CLI script:
 
 ```bash
-node bin/aiml-superagent.js check .
+npm i -D @aimlsuperagent/agent
+npx aiml-superagent check .
 ```
-

package/docs/10-adoption-playbook.md

@@ -13,7 +13,8 @@ Add:
 Run:
 
 ```bash
-node bin/aiml-superagent.js check .
+npm i -D @aimlsuperagent/agent
+npx aiml-superagent check .
 ```
 
 Replace every placeholder before relying on the output.
@@ -59,4 +60,3 @@ Review notes regularly:
 - mark assumptions explicitly
 
 The framework fails if notes become a junk drawer.
-

package/docs/13-package-analytics.md

@@ -0,0 +1,78 @@
+# Package Analytics
+
+AiML SuperAgent package analytics is opt-in.
+
+The CLI does not send analytics unless one of these is true:
+
+- `AIML_SUPERAGENT_ANALYTICS=1` is set.
+- The command is run with `--analytics`.
+
+Use `--no-analytics` to disable analytics for one command even when the environment variable is enabled.
+
+## Why It Exists
+
+Package analytics helps answer operational questions without weakening the framework's privacy and secret-safety rules:
+
+- Which CLI commands are used?
+- Are readiness checks passing?
+- Are release checks failing before publish?
+- Which Node major versions need support?
+- Are commands running locally or in CI?
+
+## What Is Sent
+
+When enabled, the CLI sends one best-effort event per command:
+
+- package name
+- package version
+- command name
+- result status
+- exit code
+- command duration
+- Node major version
+- operating system platform
+- CPU architecture
+- CI flag
+- selected command options
+- readiness label and finding counts for `check`
+- action counts for `init`
+
+## What Is Never Sent
+
+The CLI must not send:
+
+- file contents
+- note contents
+- absolute paths
+- repo names
+- project names
+- remote URLs
+- environment variable values
+- secrets or credentials
+- source code snippets
+
+## Endpoint
+
+By default, events are sent to:
+
+```bash
+https://aimlsuperagent.com/api/visitor-track
+```
+
+Use a compatible endpoint if you want to collect events somewhere else:
+
+```bash
+AIML_SUPERAGENT_ANALYTICS=1 \
+AIML_SUPERAGENT_ANALYTICS_ENDPOINT=https://example.com/api/track \
+aiml-superagent check .
+```
+
+The endpoint receives a generic tracking payload with `eventName`, `siteName`, `path`, `title`, and `data`.
+
+Like any HTTP request, the receiving endpoint may also receive normal request metadata such as IP address and user-agent.
+
+## Failure Behavior
+
+Analytics is best-effort. Network errors, timeouts, invalid endpoints, and server failures are ignored by the CLI.
+
+Analytics must never change the command output, exit code, or readiness result.

package/docs/npm-private-publishing.md

@@ -6,19 +6,11 @@ This repository is prepared for a private npm package named:
 @aimlsuperagent/agent
 ```
 
-Do not publish until npm confirms that the `@aimlsuperagent` scope is owned by the correct account or organization and private packages are enabled.
+The package is currently published as a private/restricted npm package. Users who are not authenticated and authorized will see npm `404 Not Found` errors that can look like the package or organization does not exist.
 
 ## Current Safety State
 
-`package.json` intentionally keeps:
-
-```json
-"private": true
-```
-
-That blocks accidental publishing.
-
-The package also includes:
+`package.json` includes:
 
 ```json
 "publishConfig": {
@@ -29,7 +21,7 @@ The package also includes:
 
 Restricted access is the npm setting required for a private scoped package.
 
-## Confirm Scope Ownership
+## Confirm Current Access
 
 Log in:
 
@@ -42,10 +34,37 @@ Check organization or scope access:
 
 ```bash
 npm org ls aimlsuperagent
-npm access ls-packages @aimlsuperagent
+npm team ls aimlsuperagent
+npm team ls aimlsuperagent:developers
+npm access get status @aimlsuperagent/agent
+npm access list packages aimlsuperagent:developers
+```
+
+Expected current shape:
+
+- package status: `private`
+- org owner: `aimlnexus`
+- install team: `aimlsuperagent:developers`
+- team package access: `@aimlsuperagent/agent` read-only
+
+## Add A Private Package User
+
+Use the person's npm username, not their email address.
+
+```bash
+npm org set aimlsuperagent npm_username developer
+npm team add aimlsuperagent:developers npm_username
+```
+
+The user must accept the npm organization invite, then run:
+
+```bash
+npm login
+npm i -g @aimlsuperagent/agent
+aiml-superagent --help
 ```
 
-If those commands fail because the scope or organization does not exist, create or claim the npm organization/scope before publishing.
+If they still see `404 Not Found`, they are either not logged in, have not accepted the org invite, are not in the `developers` team, or are using a different npm registry.
 
 ## Dry Run
 
@@ -60,9 +79,9 @@ Review the file list. It should include docs, templates, examples, schemas, the
 
 ## Publishing Procedure
 
-Only after private package access is confirmed:
+For a new private version:
 
-1. Remove `"private": true` from `package.json` in a dedicated publish commit.
+1. Bump the package version.
 2. Run:
 
 ```bash
@@ -73,6 +92,24 @@ npm publish --access restricted
 
 Do not run `npm publish --access public`.
 
+## Trusted Publishing
+
+npm recommends Trusted Publishing for automation and CI/CD. This repository includes:
+
+```text
+.github/workflows/npm-publish.yml
+```
+
+Configure the trusted publisher in npm package settings:
+
+- Provider: GitHub Actions
+- Organization or user: `marvinbfreedman`
+- Repository: `aimlsuperagent`
+- Workflow filename: `npm-publish.yml`
+- Allowed action: `npm publish`
+
+After that, use GitHub Actions > Publish npm package > Run workflow. The workflow uses GitHub OIDC instead of a long-lived `NPM_TOKEN`.
+
 ## Install
 
 Authorized users can install globally:
@@ -86,4 +123,3 @@ aiml-superagent --help
 ## Failure Rule
 
 If npm cannot confirm restricted/private access, do not publish. Keep using the private GitHub repo or a private tarball.
-

package/docs/release-checklist.md

@@ -31,8 +31,11 @@ git status --short
 Optional:
 
 ```bash
-node bin/aiml-superagent.js init /tmp/superagent-smoke
-node bin/aiml-superagent.js check /tmp/superagent-smoke
+mkdir -p /tmp/superagent-smoke
+cd /tmp/superagent-smoke
+npm i -D @aimlsuperagent/agent
+npx aiml-superagent init .
+npx aiml-superagent check .
 ```
 
 ## Publication

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aimlsuperagent/agent",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A token-efficient operating framework for AI coding assistants.",
   "type": "module",
   "bin": {
@@ -41,10 +41,10 @@
   "homepage": "https://aimlsuperagent.com",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/whisperaiml/superagent-repo.git"
+    "url": "git+https://github.com/marvinbfreedman/aimlsuperagent.git"
   },
   "bugs": {
-    "url": "https://github.com/whisperaiml/superagent-repo/issues"
+    "url": "https://github.com/marvinbfreedman/aimlsuperagent/issues"
   },
   "engines": {
     "node": ">=18"