knowingfyi 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sarah Simionescu
+
+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, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+# Knowing CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The npm package is `knowingfyi`; its installed commands are `knowingfyi` and `knowing`. Requires Node.js 24 or newer.
+
+The planned platform command is:
+
+```sh
+npx knowingfyi add-skill 'brickspacelab/store-skills'
+```
+
+Bare owner/repository targets default to https://knowing.fyi on first use. An explicit --site, KNOWING_SITE, or saved login site overrides that default. Domain-qualified targets select their own HTTPS origin and resolve the owner/repository release. Explicit `/s/<project>` URLs and self-hosted origins remain supported. This package must be published and the domain configured before the platform example is usable.
+
+Install a published project in your codebase:
+
+```sh
+npx knowingfyi add-skill https://your-knowing-host/s/your-project
+```
+
+That installs the full project as one skill. To install one authored skill instead:
+
+```sh
+npx knowingfyi add-skill https://your-knowing-host/s/your-project --skill audit-shopify
+```
+
+Only root `skills/<name>/SKILL.md` folders are individual skills. Supporting documents and references are bundled, rather than installed as separate skills.
+
+Install the source-defined agent or native plugin:
+
+```sh
+npx knowingfyi add-agent https://your-knowing-host/s/your-project --agent codex
+npx knowingfyi add-agent https://your-knowing-host/s/your-project --agent claude
+```
+
+Releases after 0.1.1 also accept `add-plugin` as another name for `add-agent`.
+
+Codex and Claude plugin manifests are preserved from the published source commit. Restart your coding agent after native registration.
+
+Set up the source-defined GitHub Action:
+
+```sh
+npx knowingfyi init-ci https://your-knowing-host/s/your-project
+```
+
+The command creates a pinned workflow and prints required secrets. Existing workflows are preserved. Review, commit and push the generated files.
+
+Use `--free` for free content or `--premium` for the complete paid projection. When access is needed, the CLI signs in once if it must (approval continues to the release's access page in the same tab), prints and opens the access link, and installs the same release once the server confirms access. `--no-browser` prints the link and still waits. Revoked access and tiers that aren't for sale stop at once. Purchases require the creator's checkout to be enabled; the CLI never grants access itself. CI uses a `KNOWING_INSTALL_TOKEN` secret instead of browser sign-in; create it with `knowing login --site https://your-knowing-host --install-only | gh secret set KNOWING_INSTALL_TOKEN`.
+
+Publishing and source-grounded docs are also available through `publish`, `sync`, `docs`, `search`, `ask`, `mcp` and `mcp-config`. Run `--help` for the command overview.
+
+## Sign in for docs and MCP
+
+`docs`, `search`, `ask` and `mcp` need a customer token for a member of the project or a subscriber to its top tier. Sign in once per Knowing host:
+
+```sh
+npx knowingfyi login --site https://your-knowing-host
+```
+
+The browser approval stores a customer token locally for 30 days, and the commands send it to that host. On another machine or in CI, set `KNOWING_CUSTOMER_TOKEN` with `KNOWING_SITE` naming the same host. `logout` removes the local token; revoke the terminal under Authorized devices to disable it. Customer-token reading, `knowing token`, `--install-only` and the `KNOWING_SITE` check arrive with the release after 0.1.1.
+
+## When your Knowing host changes
+
+Sign in again with `knowing login --site https://your-new-knowing-host`, then use that origin in project URLs and `--site` arguments. Saved customer logins belong to their original origin; do not copy credential files or expect a redirect to transfer the login.
+
+Update `KNOWING_SITE`, MCP server URLs and any vendored workflow project URLs deliberately. Published 0.2.0 uses `--space` / `KNOWING_SPACE` for docs, publishing and MCP; the current source adds `--project` / `KNOWING_PROJECT` for the next release while retaining the old aliases. Check the installed version's `--help` before changing those arguments.
+
+The CLI rejects API redirects, and publishing/install secrets have different capabilities from customer logins. Existing self-hosted and local origins remain supported. Operators can use the [platform domain cutover runbook](https://github.com/BrickspaceLab/knowing/blob/main/docs/knowing/platform-domain-cutover.md) to plan compatibility and rollback.
+
+Node.js 24 or newer is required. See [authoring skills and source configuration](https://github.com/BrickspaceLab/knowing/blob/main/docs/knowing/release-source.md).

package/knowing-cli.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { main as skills } from "./knowing-skills.mjs";
+import { main as automation } from "./knowing.mjs";
+
+const args = process.argv.slice(2);
+const installers = [
+  "add-skill",
+  "add-plugin",
+  "add-agent",
+  "init-ci",
+  "login",
+  "logout",
+  "token",
+  "add",
+];
+if (!args.length || args.includes("--help")) {
+  process.stdout.write(
+    "Knowing: add-skill, add-plugin, init-ci PROJECT_URL\nOptions: --skill NAME, --agent codex|claude, --version VERSION, --free, --premium\nLogin: knowing login|logout|token --site SITE_ORIGIN\nCI install secret: knowing login --site SITE_ORIGIN --install-only\nPublishing and docs: knowing docs|search|ask|sync|publish|mcp|mcp-config --project PROJECT_URL\nCreator publishing setup: knowing init-ci --project PROJECT_URL\n",
+  );
+} else {
+  const publisherSetup =
+    args[0] === "init-ci" &&
+    (args.includes("--project") || args.includes("--space"));
+  (installers.includes(args[0]) && !publisherSetup
+    ? skills(args)
+    : automation(args)
+  ).catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  });
+}