@datafog/fogclaw 0.1.0

package/docs/plans/active/2026-02-17-feat-release-fogclaw-via-datafog-package-plan.md

@@ -0,0 +1,318 @@
+---
+slug: 2026-02-17-feat-release-fogclaw-via-datafog-package
+status: active
+phase: plan
+plan_mode: execution
+detail_level: more
+priority: high
+owner: DataFog Platform Team
+---
+
+# Enable an interim DataFog-owned `@datafog/fogclaw` release path
+
+This Plan is a living document. The sections `Progress`, `Surprises & Discoveries`, `Decision Log`, `Outcomes & Retrospective`, and `Revision Notes` must be kept current as work proceeds.
+
+This plan is maintained in accordance with `docs/PLANS.md`.
+
+## Purpose / Big Picture
+
+Users should be able to install and use FogClaw today from a DataFog-owned namespace without waiting for official OpenClaw plugin listing approval. The result should be a published package `@datafog/fogclaw` that can be installed with `openclaw plugins install @datafog/fogclaw`, loads correctly through OpenClaw plugin discovery, and exposes the same guardrail + tool behavior that was already validated for the merged FogClaw line.
+
+## Progress
+
+- [x] (2026-02-17T18:52:00Z) P1 [M1] Confirmed baseline package identity references and package files in the DataFog repo.
+- [x] (2026-02-17T18:53:00Z) P2 [M1] Updated `package.json` and user docs to `@datafog/fogclaw`.
+- [x] (2026-02-17T18:54:00Z) P3 [M1] Updated `package-lock` metadata and refreshed scope for build/release artifacts.
+- [x] (2026-02-17T18:55:00Z) P4 [M2] Re-ran build/test/smoke + `npm pack --json` + `npm publish --dry-run` validations.
+- [x] (2026-02-17T18:56:00Z) P5 [M2] Verified `openclaw plugins install` against the built `datafog-fogclaw-0.1.0.tgz` in a clean runtime; plugin now loads as `fogclaw` with status `loaded` and tools `fogclaw_scan, fogclaw_redact`.
+- [ ] (2026-02-17T18:56:00Z) P5 [M2] Verify `openclaw plugins install @datafog/fogclaw` with live npm resolution (blocked until package is published).
+- [ ] (2026-02-17T18:56:00Z) P6 [M3] Prepare and execute V1 publish/release of `@datafog/fogclaw` (publishing blocked by org access/2FA status in current environment).
+- [x] (2026-02-17T18:57:00Z) P7 [M3] Capture release artifacts and update evidence notes; add follow-up for dependency install blocker in OpenClaw install path.
+
+
+## Surprises & Discoveries
+
+- Observation: In the DataFog repo, multiple docs and user-facing examples currently point to `@openclaw/fogclaw`, and migration must be done consistently across `README.md`, `docs/plugins/fogclaw.md`, and install examples to avoid user confusion.
+  Evidence: `rg -n "@openclaw/fogclaw|openclaw plugins install"` in `/Users/sidmohan/Projects/datafog/fogclaw`.
+
+- Observation: `package-lock.json` pins package metadata to `@openclaw/fogclaw` and must be regenerated after namespace rename.
+  Evidence: top-level `package-lock.json` package metadata `name` field.
+
+- Observation: `openclaw plugins install` of a clean extracted `datafog-fogclaw-0.1.0.tgz` now completes successfully on a clean runtime.
+  Evidence: `openclaw plugins install /Users/sidmohan/Projects/datafog/fogclaw/datafog-fogclaw-0.1.0.tgz`, `openclaw plugins info fogclaw`, and `openclaw plugins list` all report plugin `fogclaw` as `loaded` with tools.
+
+- Observation: The prior `TypeError: Cannot read properties of undefined (reading 'trim')` install failure was caused by OpenClaw's `registerTool` contract when tool objects omit a top-level `name`.
+  Evidence: `src/plugins/registry.ts` in OpenClaw (`registerTool` maps `tool.name` without null-guard); fixed in this repository by adding `name` fields to both tool objects.
+
+- Observation: `openclaw plugins install @datafog/fogclaw` still fails in this environment with `404 Not Found - GET https://registry.npmjs.org/@datafog%2ffogclaw` because the scoped package is not yet published to npm.
+  Evidence: CLI output from `openclaw plugins install @datafog/fogclaw` in current machine state.
+
+- Observation: plugin loads with runtime warning about optional `sharp` optional dependency for GLiNER image ops; warning does not prevent plugin load.
+  Evidence: repeat `Cannot find module '../build/Release/sharp-darwin-arm64v8.node'` messages from `openclaw plugins install` run on clean state.
+
+## Decision Log
+
+- Decision: Keep package behavior unchanged while implementing namespace migration and release plumbing.
+  Rationale: V1 goal is immediate user availability through DataFog namespace, not plugin runtime changes.
+  Date/Author: 2026-02-17T10:57:00Z / sidmohan
+
+- Decision: Maintain plugin `id: "fogclaw"` and `openclaw.extensions` compatibility.
+  Rationale: OpenClaw discovery is keyed by plugin id in manifest and extension path; changing `id` would require user-facing config migration.
+  Date/Author: 2026-02-17T10:57:00Z / sidmohan
+
+- Decision: Use `@datafog/fogclaw` for interim installs and document fallback to official listing work separately.
+  Rationale: This matches the user objective for independently publishable DataFog namespace while official inclusion is pending.
+  Date/Author: 2026-02-17T10:57:00Z / sidmohan
+
+- Decision: Keep behavioral compatibility unchanged for the V1 scope.
+  Rationale: The goal is install-path enablement and namespace migration, not feature changes to detection/redaction behavior.
+  Date/Author: 2026-02-17T18:57:00Z / sidmohan
+
+- Decision: Add a targeted registration compatibility fix for OpenClaw API expectations while keeping runtime behavior unchanged.
+  Rationale: OpenClaw's `registerTool` requires a tool `name` field in object registrations to avoid `trim` crashes; adding `name` fields in FogClaw's tool registrations is a non-functional compatibility patch and required to complete installability.
+  Date/Author: 2026-02-17T19:08:00Z / sidmohan
+
+## Outcomes & Retrospective
+
+- V1 package identity migration and documentation updates are complete in the DataFog repo with no runtime behavior changes.
+- Local validation confirms namespace rename compiles and tests (`npm run build`, `npm run test`, `npm run test:plugin-smoke`) continue to pass.
+- `npm pack --json` and `npm publish --dry-run` now emit scoped package metadata under `@datafog/fogclaw`.
+- `openclaw plugins install` against a clean temporary state and local `datafog-fogclaw-0.1.0.tgz` now succeeds; `openclaw plugins info fogclaw` shows status `loaded` and tools `fogclaw_scan`, `fogclaw_redact`.
+- `openclaw plugins install @datafog/fogclaw` via npm registry is still blocked in this environment by publish visibility (`404 Not Found`) until release is live.
+- GLiNER/`sharp` warnings are still non-fatal during plugin registration in this environment and do not prevent plugin load.
+
+
+## Context and Orientation
+
+This repository is `/Users/sidmohan/Projects/datafog/fogclaw`.
+
+Key files:
+
+- `package.json`: package identity (`name`) and plugin manifest pointer (`openclaw.extensions`).
+- `package-lock.json`: locked package metadata used by npm publish and reproducibility checks.
+- `openclaw.plugin.json`: plugin manifest required by OpenClaw (`id`, config schema, metadata).
+- `dist/index.js`: compiled plugin entrypoint referenced by `openclaw.extensions`.
+- `src/index.ts`: plugin registration (`before_agent_start`, `fogclaw_scan`, `fogclaw_redact`).
+- `tests/plugin-smoke.test.ts`: local contract check for hook/tool registration.
+- `README.md` and `docs/plugins/fogclaw.md`: primary install and usage documentation.
+- `/Users/sidmohan/Projects/datafog/openclaw` provides target runtime install behavior for `openclaw plugins install`.
+
+**OpenClaw install flow (important for this initiative):**
+`openclaw plugins install <npm-spec>` invokes `npm pack`, extracts into plugin extension directory, records install metadata, and loads the extracted package through plugin manifest/entrypoint discovery.
+
+## Milestones
+
+### Milestone 1 — Namespace migration in DataFog repo
+
+Rename the package to `@datafog/fogclaw` across package metadata and documentation without changing runtime behavior. This milestone exists so users can consistently install the package from DataFog namespace and the published tarball name matches the user-facing command.
+
+### Milestone 2 — Validation of local contract and installability
+
+Prove the renamed package remains install-ready by running build/tests/pack checks and an end-to-end OpenClaw install smoke flow. This milestone ensures compatibility with OpenClaw’s plugin loader and confirms no manifest or entrypoint regressions.
+
+### Milestone 3 — Release and evidence publishing
+
+Publish V1 package release to npm, then record release evidence and update operational/runbook notes so users can reliably install `@datafog/fogclaw` today.
+
+## Plan of Work
+
+Work should proceed in small, testable edits.
+
+First, update DataFog package metadata and references to the desired scope and verify there are no conflicting names left behind. This includes package name, lockfile metadata, user documentation commands, and plugin docs in the DataFog repo.
+
+Second, run an installability verification sequence in the same repo: compile and test, generate a dry-run publish artifact, and validate OpenClaw loading behavior from a clean install path using the newly scoped npm spec. For the smoke path, use either a temporary local publish or a pre-release test package if external network restrictions prevent immediate production publish.
+
+Third, perform the final publish/release steps and capture deterministic artifacts (pack info, version, install command, expected `openclaw plugin` diagnostics) in the plan’s evidence section. Keep open questions explicit if npm publish access/rate-limiting or token setup is an external blocker.
+
+## Concrete Steps
+
+From repo root `/Users/sidmohan/Projects/datafog/fogclaw`:
+
+1. Inspect current scope references.
+
+    rg -n "@openclaw/fogclaw|@datafog/fogclaw|openclaw plugins install" README.md package.json package-lock.json docs/plugins/fogclaw.md src docs/PLANS.md
+
+Expected:
+
+- Install/documentation references should consistently show `@datafog/fogclaw` (legacy `@openclaw/fogclaw` references would be migration follow-ups).
+
+2. Update package identity to DataFog namespace.
+
+    python - <<'PY'
+import json
+from pathlib import Path
+p = Path('package.json')
+obj = json.loads(p.read_text())
+obj['name'] = '@datafog/fogclaw'
+p.write_text(json.dumps(obj, indent=2) + "\n")
+print('updated', p)
+
+p = Path('package-lock.json')
+obj = json.loads(p.read_text())
+obj['name'] = '@datafog/fogclaw'
+if isinstance(obj.get('packages'), dict) and '' in obj['packages']:
+    obj['packages']['']['name'] = '@datafog/fogclaw'
+p.write_text(json.dumps(obj, indent=2) + "\n")
+print('updated', p)
+PY
+
+Expected:
+
+- Both files use `@datafog/fogclaw` as package `name`.
+- `package-lock.json` root package and lock metadata are coherent.
+
+3. Update install/docs references to the scoped package.
+
+    rg -n "@openclaw/fogclaw|openclaw plugins install @" README.md docs/plugins/fogclaw.md docs/specs/*.md docs/plans/active/*.md
+
+Then edit all DataFog user-facing examples to:
+
+- `openclaw plugins install @datafog/fogclaw`
+
+and adjust standalone import examples if they currently imply `@openclaw/fogclaw` identity.
+
+Expected:
+
+- Documentation consistently points users at `@datafog/fogclaw` for interim install path.
+- Core plugin `id` and extension path references remain unchanged.
+
+4. Rebuild and refresh lock-derived metadata as needed.
+
+    npm install
+    npm run build
+    npm test
+    npm run test:plugin-smoke
+
+Expected:
+
+- Build/test suite passes.
+- `dist/index.js` and test artifacts remain valid.
+- Plugin contract checks still pass.
+
+5. Validate package pack shape before publish.
+
+    npm pack --json
+    npm publish --dry-run
+
+Expected:
+
+- Tarball contains `dist/index.js` and `openclaw.plugin.json` and `package.json`.
+- No unintended paths (e.g., local `.git`, build cache, editor artifacts) leak into the packed payload.
+
+6. Verify install path from OpenClaw using scoped spec on a local/clean extension path.
+
+    openclaw plugins install @datafog/fogclaw
+    openclaw plugins info fogclaw
+    openclaw plugins list | rg fogclaw
+
+Expected:
+
+- `fogclaw` plugin appears and can be enabled/referenced in OpenClaw config.
+- No manifest/schema errors are thrown in plugin load.
+
+## Validation and Acceptance
+
+A completed V1 initiative is successful when all commands below pass in this repo and in an `openclaw` runtime that can install third-party packages.
+
+- Run:
+  - `npm install`
+  - `npm run build`
+  - `npm test`
+  - `npm run test:plugin-smoke`
+  - `npm pack --json`
+  - `npm publish --dry-run`
+
+Expect:
+
+- Plugin build/tests pass.
+- Pack metadata is minimal and includes `openclaw.plugin.json` + `dist/index.js`.
+- Installability command either succeeds with a published `@datafog/fogclaw` package or demonstrates a reproducible blocker (e.g., publish access) with mitigation.
+
+- `openclaw plugins install @datafog/fogclaw`
+- `openclaw plugins info fogclaw`
+- `openclaw plugins list | rg fogclaw`
+
+Expect:
+
+- Plugin installation metadata registers as `fogclaw` and lists both hook/tool availability from manifest.
+- `openclaw plugins info fogclaw` shows no critical errors.
+
+## Idempotence and Recovery
+
+- Re-running namespace renames is safe if done as a single set of edits (`package.json`, `package-lock.json`, docs).
+- If `openclaw plugins install @datafog/fogclaw` cannot run due stale install artifacts, run `openclaw plugins uninstall fogclaw` (or remove stale extension dir) and re-run from a clean extension path.
+- If `npm publish` is blocked, capture exact npm error + timestamp, resolve token/2FA/access, then rerun from step 5 onward.
+- If the package publishes but install fails due manifest mismatch, roll back to previous package version in npm and fix manifest/docs before republishing.
+
+## Artifacts and Notes
+
+- Scope migration evidence:
+
+    package: @datafog/fogclaw
+    version: 0.1.0
+    `npm pkg get name` output: `"@datafog/fogclaw"`
+    `npm pkg get openclaw` output:
+    `{"extensions":["./dist/index.js"]}`
+
+- Contract smoke evidence:
+
+    `node - <<'NODE'
+    import plugin from './dist/index.js';
+    console.log(typeof plugin?.register, plugin?.id, plugin?.name);
+    NODE`
+    => `function fogclaw FogClaw`
+
+- Reproducibility evidence:
+  - `npm pack --json` output includes `datafog-fogclaw-0.1.0.tgz` and `openclaw.plugin.json`/`dist/index.js` in file list.
+  - `npm publish --dry-run` succeeded and produced scoped package manifest notice.
+
+- Installability evidence:
+  - `openclaw plugins install @datafog/fogclaw` currently fails with `npm 404 Not Found` until package publish is live.
+  - `openclaw plugins install` against local `datafog-fogclaw-0.1.0.tgz` in a clean temp runtime now succeeds and reports plugin status `loaded` with tools `fogclaw_scan`, `fogclaw_redact`.
+  - GLiNER startup logs still surface optional `sharp` module warnings, but plugin registration now succeeds.
+
+- `git rev-parse HEAD` (of implementation snapshot): capture before final merge.
+
+- Scoped package discoverability: not yet in npm registry during this environment run.
+
+
+## Interfaces and Dependencies
+
+- OpenClaw plugin package contract:
+  - `package.json` field `openclaw.extensions` still points to `./dist/index.js`.
+  - `openclaw.plugin.json` remains installable by OpenClaw manifest parser.
+- Build and verification commands rely on:
+  - `typescript`, `vitest`, and Node runtime already present in project.
+- Publish path depends on npm credentials and any 2FA / publish policy in DataFog org scope.
+
+## Pull Request
+
+- pr: <url>
+- branch:
+- commit:
+- ci:
+
+## Review Findings
+
+- Pending until review stage.
+
+## Verify/Release Decision
+
+- decision: blocked
+- date: 2026-02-17T19:08:00Z
+- open findings by priority (if any): pending
+- evidence:
+  - installability in clean runtime succeeds for local `datafog-fogclaw-0.1.0.tgz` after tool-name registration fix
+  - scoped package install still returns registry 404 (not yet published)
+- rollback: revert to previous working scoped package state (or keep changes in branch) if publish credentials/visibility unavailable
+- post-release checks:
+  - `openclaw plugins install @datafog/fogclaw`
+  - `openclaw plugins info fogclaw`
+  - `openclaw plugins list | rg fogclaw`
+- owner: sidmohan
+
+## Revision Notes
+
+- 2026-02-17T10:57:00Z: Initialized plan for V1 scoped-release path in `@datafog/fogclaw` and documented zero-logic-change constraints for immediate installability milestone.
+- 2026-02-17T18:57:00Z: Completed namespace migration in package metadata and install/docs (`package.json`, `package-lock.json`, `README.md`, `docs/plugins/fogclaw.md`). Ran full local validation (`npm run build`, `npm run test`, `npm run test:plugin-smoke`, `npm pack --json`, `npm publish --dry-run`) and documented install blocker (package not yet published to npm).
+- 2026-02-17T19:08:00Z: Fixed OpenClaw compatibility in `src/index.ts` by adding explicit `name` fields to `fogclaw_scan` and `fogclaw_redact` tool registrations to avoid undefined `.trim()` during registration; verified clean-runtime install/load succeeds with local tarball (`openclaw plugins install <tgz>`, `plugins info`, `plugins list`).

package/docs/plans/active/2026-02-17-feat-submit-fogclaw-to-openclaw-plan.md

@@ -0,0 +1,244 @@
+---
+slug: 2026-02-17-feat-submit-fogclaw-to-openclaw
+status: active
+phase: plan
+plan_mode: execution
+detail_level: more
+priority: high
+owner: sidmohan
+---
+
+# Submit FogClaw to OpenClaw's official plugin submission path
+
+This plan is a living document. Keep `Progress`, `Surprises & Discoveries`, `Decision Log`, `Outcomes & Retrospective`, and `Revision Notes` current as work progresses.
+
+This plan must be maintained in accordance with `docs/PLANS.md`.
+
+## Purpose / Big Picture
+
+The plugin is already merged in `DataFog/fogclaw` and ready for publication. This initiative moves beyond local repository hardening to complete the **official OpenClaw submission process** in the upstream ecosystem, so maintainers and users can discover FogClaw through OpenClaw’s normal plugin intake path.
+
+After this initiative, a reviewer should be able to find a dedicated upstream OpenClaw PR containing reproducible evidence for plugin loadability, tool/guardrail behavior, and package identity, with clear status and follow-up notes if maintainers request changes.
+
+## Progress
+
+- [x] (2026-02-17T01:56:00Z) P1 [Setup] Create submission intent spec for official OpenClaw side flow in `docs/specs/2026-02-17-feat-submit-fogclaw-to-openclaw.md`.
+- [x] (2026-02-17T01:58:00Z) P2 [M1] Read and align the plan against repository conventions (`docs/PLANS.md` + `docs/runbooks/`) and confirm open questions from spec.
+- [x] (2026-02-17T02:05:00Z) P3 [M1] Confirm target OpenClaw submission repository/path and required PR checklist/template.
+- [x] (2026-02-17T02:20:00Z) P4 [M2] Draft external PR body with reproducible evidence block and maintainer-facing rationale.
+- [x] (2026-02-17T02:28:00Z) P5 [M2] Open upstream OpenClaw PR from branch containing only FogClaw submission/supporting docs (`docs/plugins/fogclaw.md`).
+- [ ] (2026-02-17T02:40:00Z) P6 [M3] Record maintainer feedback and implement any required follow-up in repository or PR only when explicitly requested.
+- [ ] (2026-02-17T02:50:00Z) P7 [M3] Update this plan `Pull Request` and `Verify/Review` sections with final submission state and closeout status.
+
+## Surprises & Discoveries
+
+- Observation: OpenClaw intake guidance is not documented as a dedicated "plugin submission" checklist; the operative path is standard upstream PR flow on `openclaw/openclaw` with the canonical PR template.
+  Evidence: repo-level review (`.github/pull_request_template.md`) plus `docs/reference/RELEASING.md` plugin scope notes.
+
+- Observation: `DataFog/fogclaw` is not a fork of `openclaw/openclaw`, so direct cross-repo PR creation from that repo was not possible via `gh`.
+  Resolution at the time: opened a temporary PR from a personal fork (`#18779`) for speed, then migrated to `DataFog/openclaw` when the org-owned upstream fork became available.
+
+- Observation: A DataFog-owned OpenClaw fork improves ownership alignment for future external submissions.
+  Resolution: created `DataFog/openclaw` fork and moved upstream submission PR to come from `DataFog:openclaw-upstream-submission` (PR `#18791`).
+
+## Decision Log
+
+- Decision: Scope this initiative to upstream OpenClaw submission only, with zero functional/plugin code changes.
+  Rationale: Plugin behavior and API are already stabilized and merged locally; additional code changes would dilute the submission objective and risk destabilizing already verified artifacts.
+  Date/Author: 2026-02-17T01:58:00Z / sidmohan
+
+- Decision: Keep `@openclaw/fogclaw` as the canonical package identity and treat manifest evidence (`openclaw.plugin.json`, `dist/index.js`, and install command) as mandatory submission evidence.
+  Rationale: Submission evidence must be reproducible and match what was already validated in the internal PR phase.
+  Date/Author: 2026-02-17T01:58:00Z / sidmohan
+
+- Decision: Use standard upstream PR delivery on `openclaw/openclaw` and open from a true fork rather than the DataFog repo.
+  Rationale: `DataFog/fogclaw` is not a fork of the target repo, and `gh` blocks non-fork cross-repo PRs with direct refs.
+  Date/Author: 2026-02-17T02:29:00Z / sidmohan
+
+- Decision: Prefer a `DataFog`-owned fork (`DataFog/openclaw`) as the canonical upstream fork source for future plugin-submission PRs.
+  Rationale: Ownership alignment and provenance are clearer for external partner submissions when PRs originate from the company/org fork.
+  Date/Author: 2026-02-17T02:46:00Z / sidmohan
+
+## Outcomes & Retrospective
+
+- A merged baseline exists in `DataFog/fogclaw` and the next step is organizational rather than technical.
+- Submission-specific actions are now separated from detection hardening to reduce rework.
+
+## Context and Orientation
+
+This repository (`/Users/sidmohan/Projects/datafog/fogclaw`) currently contains the source plugin, build outputs configuration, and release evidence updates already merged into `main`.
+
+Key runtime files are:
+
+- `src/index.ts`: registers `before_agent_start`, `fogclaw_scan`, and `fogclaw_redact`.
+- `openclaw.plugin.json`: plugin manifest used by OpenClaw to discover package entry.
+- `package.json`: plugin identity (`name: @openclaw/fogclaw`) and `openclaw.extensions` entry.
+- `README.md`: reviewer-facing install/evidence commands.
+- `tests/plugin-smoke.test.ts`: non-mocked contract test proving tool and hook behavior on a local mock API.
+- `docs/plans/active/2026-02-16-feat-openclaw-official-submission-plan.md`: closed internal submission-readiness initiative details.
+
+For this initiative, a repository branch/PR in an external OpenClaw repo is an **upstream submission route**: it is the place maintainers expect to receive plugin listing evidence. The core task is therefore documentation and submission logistics, not code edits.
+
+## Milestones
+
+### Milestone 1 - Confirm upstream submission target and acceptance expectations
+
+At the end of this milestone, the team has identified exactly where and how OpenClaw accepts plugin submissions and what explicit checklist fields must be present in the upstream PR. This is required before drafting or opening the PR and avoids submitting to the wrong repo/branch.
+
+### Milestone 2 - Prepare and open the upstream OpenClaw PR
+
+At the end of this milestone, a ready-to-review OpenClaw PR exists with clear install and verification evidence. The PR body should include commands and expected output and point to this repo’s validated artifact path. The branch should contain only submission-facing changes if any are required, not detection logic changes.
+
+### Milestone 3 - Maintain submission loop and close evidence handoff
+
+At the end of this milestone, maintainer feedback is either satisfied or clearly documented as a blocker with exact follow-up action. This plan is updated with final PR status, and the submission outcome is captured for handoff or continue-work.
+
+## Plan of Work
+
+The work begins by confirming the exact OpenClaw repository path for official plugin submissions. If the target and PR template are known from existing policy, proceed to drafting the upstream PR body.
+
+Draft a clean upstream submission body in local notes, ensuring it contains explicit commands and expected outputs from this repository’s `main` branch state. Include the merge commit reference and package identity evidence (`npm pkg get openclaw`, smoke import check from `dist/index.js`, and test status).
+
+Open the upstream PR with a title and body that maps directly to maintainer review needs, avoiding implementation detail beyond what was already merged internally. If no additional documentation changes are required locally, this milestone should avoid new feature edits.
+
+If maintainers request adjustments, isolate required follow-up work to the smallest possible set. If changes are non-code metadata tasks (for example: clarifying submission checklist text), prefer direct PR updates; if code/manifest edits are requested, open a follow-up branch with precise evidence.
+
+## Concrete Steps
+
+From repo root `/Users/sidmohan/Projects/datafog/fogclaw`:
+
+1) Confirm local state and current merged commit hash:
+
+    git log --oneline --max-count=3
+
+Expected (example pattern):
+
+    <hash> docs(plan): record PR merge completion on main
+    3deae34 Merge pull request #1 from DataFog/openclaw-plugin-submission
+
+2) Validate submission evidence locally one more time:
+
+    npm test
+    npm run build
+    npm run test:plugin-smoke
+    npm pkg get openclaw
+    node - <<'NODE'
+import plugin from './dist/index.js';
+console.log(typeof plugin?.register === 'function', plugin?.id, plugin?.name);
+NODE
+
+Expected:
+
+    Test and build complete successfully.
+    npm pkg get openclaw returns { "extensions": ["./dist/index.js"] }.
+    node import prints `true fogclaw FogClaw`.
+
+3) Capture upstream submission inputs:
+
+    openclaw-target=<openclaw-repo-path>
+    openclaw-pr-title="feat(openclaw): official fogclaw plugin submission"
+
+Then prepare PR body fields including: package ID, install command, evidence command list, and maintainer-impact notes.
+
+4) Open upstream PR (using OpenClaw submission target):
+
+    gh pr create --repo <openclaw-target> --base main --head <your-branch> --title "$openclaw-pr-title" --body-file <generated-body>
+
+Expected:
+
+    PR URL printed and state set to open.
+
+5) Track review and iterate:
+
+    gh pr view --repo <openclaw-target> --json number,title,state,reviewDecision,url,headRefName,baseRefName
+    gh pr checks --repo <openclaw-target> --watch
+
+Expected:
+
+    Visible PR state and any required checks or maintainer feedback.
+
+## Validation and Acceptance
+
+A successful outcome for this initiative is: the upstream submission PR is open in the official OpenClaw path and contains reproducible proof that the plugin package is installable and contract-safe.
+
+Specifically:
+
+- The PR body includes install and verification commands from this merged plugin state.
+- Evidence output matches this repo’s local validations (tests, build, smoke, package manifest path).
+- No code changes are introduced without a maintainer-triggered request.
+- If maintainer asks for changes, they are closed with a targeted follow-up and documented in this plan.
+
+## Idempotence and Recovery
+
+If the upstream target path is wrong, update only the submission-path variables and rerun steps 3–5. If review feedback requires code edits, apply minimal patches, rerun the same local evidence commands, and either amend or recreate the upstream PR as needed. If a submission PR was opened incorrectly, close it with a short note and open a corrected PR to avoid mixed evidence.
+
+Rollback during this initiative is low-risk: no functional code changes are planned, so revert only submission artifacts or follow-up docs after maintainer feedback confirmation.
+
+## Artifacts and Notes
+
+- Internal merge evidence already exists in `docs/plans/active/2026-02-16-feat-openclaw-official-submission-plan.md` and includes:
+  - `npm test` run success
+  - `npm run build` success
+  - `npm run test:plugin-smoke` pass
+  - `npm pkg get openclaw` and import smoke output
+
+- Upstream PR status:
+  - PR `#18779` was created from a temporary personal fork and then superseded by PR `#18791` from `DataFog/openclaw` to align with official ownership.
+  - PR `#18791` is now the active upstream request with submission body + reproducible evidence.
+  - Target repository: `openclaw/openclaw` (main branch).
+  - Required template source: `.github/pull_request_template.md`.
+  - Plugin release scope constraints used from `docs/reference/RELEASING.md` (npm plugin scope + existing plugin list expectations).
+
+- Registry/installability note:
+  - `npm view @openclaw/fogclaw version` currently returns `E404` (package not yet visible in registry from this environment). Actual runtime/installability remains coupled to maintainer publish flow. This is intentionally tracked as evidence gap outside plugin logic scope.
+
+## Interfaces and Dependencies
+
+No new runtime interfaces are introduced in this initiative. The key artifacts to reference are:
+
+- `package.json` `openclaw.extensions` + `name`.
+- `openclaw.plugin.json`.
+- `README.md` evidence section (already updated).
+- `tests/plugin-smoke.test.ts` for local behavioral proof.
+- GitHub CLI (`gh`) for PR operations.
+
+The external OpenClaw PR should reference these repo files without changing their internals in this phase.
+
+## Pull Request
+
+- pr: https://github.com/openclaw/openclaw/pull/18791
+- branch: DataFog:openclaw-upstream-submission
+- commit: 2609f9838 (fork branch)
+- ci: initiated (openclaw/pull/18791 CI: docs-scope, check-docs, secrets passed; several workflows still queued for label/conformance/format checks at creation time)
+
+## Review Findings
+
+- PR #18779 was intentionally closed and superseded.
+- PR #18791 is now active and in maintainer triage.
+- Pending: check for checklist/approval or requested follow-up once review starts.
+
+## Verify/Release Decision
+
+- decision: pending (upstream PR open; final release decision deferred to maintainer review)
+- date: 2026-02-17T02:35:00Z
+- open findings by priority (if any): pending
+- evidence:
+  - `npm test`
+  - `pnpm build`
+  - `npm run test:plugin-smoke`
+  - `npm pkg get openclaw`
+  - `node` import smoke (`true fogclaw FogClaw`)
+  - upstream PR created: `https://github.com/openclaw/openclaw/pull/18791`
+  - CI snapshot at submit time: `check-docs` / `docs-scope` / `secrets` passed; `label`, `label-issues`, `formal_conformance`, `no-tabs` checks still queued
+- rollback:
+  - Close/recreate PR if maintainers request intake-path correction.
+- post-release checks:
+  - monitor review comments and any requested follow-up changes.
+  - once approved, confirm plugin docs/listing + release status in upstream merge checks.
+- owner: sidmohan
+
+## Revision Notes
+
+- 2026-02-17T01:58:00Z: Initialized plan from spec `2026-02-17-feat-submit-fogclaw-to-openclaw`. Reason: transition intent to upstream OpenClaw submission as the remaining official readiness step.
+- 2026-02-17T02:28:00Z: Opened initial upstream submission PR `https://github.com/openclaw/openclaw/pull/18779` (temporary personal-fork variant) with evidence-first PR body and `docs/plugins/fogclaw.md` content only.
+- 2026-02-17T02:47:00Z: Created official DataFog upstream fork `https://github.com/DataFog/openclaw` and moved submission PR ownership to `https://github.com/openclaw/openclaw/pull/18791` (source `DataFog:openclaw-upstream-submission`); closed PR #18779 as superseded.

package/docs/plans/tech-debt-tracker.md

@@ -0,0 +1,42 @@
+# Tech Debt Tracker
+
+General-purpose deferred-work queue. Review findings, cleanup tasks, improvement ideas — anything we want to address later but shouldn't block now. Any skill can append to this file.
+
+Treat this file as append-and-update: do not delete historical rows unless duplicated by mistake. When status changes, update both the index table row and the detail entry.
+
+## Status Semantics
+
+- `new`: captured, not yet scheduled.
+- `queued`: prioritized for a future slug.
+- `in_progress`: being addressed in an active plan.
+- `resolved`: fixed, evidence linked.
+- `wont_fix`: consciously accepted with documented rationale.
+
+## Index
+
+| ID | Date | Priority | Source | Status | Summary |
+|---|---|---|---|---|---|
+| TD-2026-02-17-01 | 2026-02-17 | high | 2026-02-17-feat-submit-fogclaw-to-openclaw-plan | resolved | Define and document the canonical upstream PR path for external plugin submissions from non-fork plugin repos.
+| TD-2026-02-17-02 | 2026-02-17 | medium | 2026-02-17-feat-submit-fogclaw-to-openclaw-plan | new | Track package scope/publish readiness (`@openclaw/fogclaw` visibility) separately from PR review progress.
+
+## Detail Entries
+
+<!-- Append new entries below this line. -->
+
+- **TD-2026-02-17-01**
+  - **Source:** initiative `docs/plans/active/2026-02-17-feat-submit-fogclaw-to-openclaw-plan.md`
+  - **Status:** resolved
+  - **Priority:** high
+  - **Owner:** sidmohan / OpenClaw intake coordination
+  - **Action:** Add and maintain the submission-runbook path so all future external plugin submissions use the same fork-first + forked PR pattern.
+  - **Evidence/Reference:** Created `DataFog/openclaw` fork and moved active PR to `openclaw/openclaw` PR #18791 from `DataFog:openclaw-upstream-submission`.
+  - **Rollback:** none; process doc update is now in place as docs-only.
+
+- **TD-2026-02-17-02**
+  - **Source:** initiative `docs/plans/active/2026-02-17-feat-submit-fogclaw-to-openclaw-plan.md`
+  - **Status:** new
+  - **Priority:** medium
+  - **Owner:** sidmohan / OpenClaw release coordinators
+  - **Action:** Add release gate that confirms `npm view @openclaw/<plugin>` visibility before merge is finalized.
+  - **Evidence/Reference:** `npm view @openclaw/fogclaw version` currently returns E404 from this environment.
+  - **Rollback:** if scope changes, update entry to `resolved` with release evidence and PR link.