# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [3.7.5] - 2026-06-17

### Added

- **`newo sandbox` connector selection (R1)** — new `--connector <connector_idn>` and `--integration <idn>` flags select which connector to chat through instead of always taking the first running connector of the `sandbox` integration (which made agents like Vibe Builder's `vibe_agent` unreachable from the CLI when another connector, e.g. `convo_agent_sandbox`, came first). `--list-connectors` prints the running connectors (with `--json` for machine output). When `--connector` is not found, the error lists the available running connectors. Without flags, behavior is unchanged (first running connector). Surfaced during PR #2076 superagent testing.
- **`newo sandbox` long messages and machine-readable output (R2)** — `--file <path>` and `--stdin` send message text without shell-argument limits (tested scenarios used 40k–400k char messages); `--timeout <seconds>` overrides the previously hardcoded 60-second response-poll limit (long VibeFlow turns ran 1–7 minutes); `--json` emits `{actor_id, persona_id, connector_idn, external_event_id, user_external_event_id, agent_external_event_id, response, elapsed_ms, timed_out, flow_idn, skill_idn, session_id}`. The `external_event_id` of the user turn is the correlation key for `newo logs --event-id`, closing the gap that previously required ad-hoc scripts importing `dist/api.js` directly.
- **`newo get-skill` / `newo update-skill` (R3)** — point inspection and point edits of a single skill on the platform by IDN path (`<skill-idn> --project <idn> --agent <idn> --flow <idn>`), with no pulled workspace required. `get-skill` shows the live model, runner_type, parameters, and prompt_script (`--json` supported). `update-skill` changes `--model <provider_idn>/<model_idn>` and/or `--script <file>`, leaving everything else untouched; `--publish` (with optional `--publish-description`) publishes the flow afterwards, otherwise changes stay draft. Warns when a local pulled workspace exists and now diverges. Covers the "switch model → run test → switch back" scenario in two commands.
- **`newo logs --name <ActionName>` (R4)** — client-side filter on `data.name` (e.g. only `Gen` or `GetMemory` action calls), replacing `--json` + jq post-filtering. Help text now documents that the model of a turn must be read from `data.source.model` in `--json` output, not inferred from actor/agent names.
- **`newo logs --raw`** — JSONL output: one JSON object per log line (sorted oldest-first), with no banners or empty-result text, so stdout is a clean machine-readable stream for piping (`newo logs --raw | jq ...`). Distinct from `--json`, which emits a single pretty-printed JSON array.
- **`src/sync/remote-skill.ts`** — shared resolver (`resolveRemoteSkill`, `parseModelFlag`) that maps a project/agent/flow/skill IDN path to platform IDs with descriptive errors listing available IDNs at the failing level.
- **20 unit tests** — 14 in `test/sandbox-skill-commands.test.js` covering connector selection (legacy first-running behavior, exact match, non-running exclusion, error listings), poll timeout override, user/agent `external_event_id` capture, IDN-path resolution, and `--model` flag parsing, plus 6 in `test/logs-command.test.js` covering `--name` client-side filtering, pagination, and `--raw` JSONL output — all against a fake axios client, no network.

## [3.7.4] - 2026-06-10

### Added

- **V2 push now creates new skills from inline flow YAML definitions.** Previously the `newo_v2` push path could only update content of skills already known to the local project map; a skill added locally to `{FlowIdn}.yaml` after the last pull was silently ignored, leaving its `.nsl`/`.nslg` script with no way to reach the platform. `V2ProjectSyncStrategy.push()` now reconciles inline skill metadata before iterating script changes: missing remote skills are created via `POST /api/v1/designer/flows/{flowId}/skills`, race-condition duplicates (already-exists on create) fall back to fetching the remote skill via `listFlowSkills` and updating it, and missing skill parameters are filled in via `POST /api/v1/designer/flows/skills/{skillId}/parameters`. The local project map and SHA256 hash store are updated atomically after the reconciliation pass.
- **Strict model validation before V2 skill writes.** New `assertSkillModelResolved` helper throws a descriptive error ("Set either skill.model.* or flow default_model_idn/default_provider_idn") when neither the inline skill nor the flow declares a model/provider, instead of letting the platform return a generic 4xx with no hint about which YAML field is missing.
- **33 unit tests** in `test/v2-push-helpers.test.js` covering `isAlreadyExistsApiError`, `assertSkillModelResolved`, `normalizeRunnerType`, `normalizeParameters`, `skillMetadataDiffers`, `buildV2SkillMetadataFromYaml`, and `createMissingSkillParameters` (stubbed API client). Regression-locks the false-positive matcher fix, the model-validation contract, the parameter-creation counting, and the model-key-order false positive.

### Fixed

- **`isAlreadyExistsApiError` no longer matches "does not exist".** The previous detector accepted any 400/409/422 response whose body contained the substring `"exist"`, which incorrectly classified "Skill does not exist" / "Flow doesn't exist" errors as duplicates and triggered a spurious reuse fallback. The matcher is now tightened to only `"already exists"` and `"duplicate key"`.
- **`validate()` reports missing scripts for YAML-declared skills.** Previously `V2ProjectSyncStrategy.validate()` only checked scripts listed in the local map; skills added directly to `{FlowIdn}.yaml` since the last pull were never validated. Validation now walks the YAML when present and surfaces a `Script file not found:` error per skill, matching the new push contract.
- **Missing-script skills are reported, not silently skipped.** Instead of a `verbose`-only "Skipping skill without local script" log, the push now records `[newo_v2] Missing script for skill {project}/{agent}/{flow}/{skill}: {path}` in the push errors. Failures are isolated per skill: one broken skill no longer aborts the push of every other flow/project in the workspace.
- **Model validation only runs before actual platform writes.** `assertSkillModelResolved` fires only when a skill is about to be created or its metadata updated — a pre-existing flow YAML without `skill.model.*` / flow `default_model_idn` no longer blocks pushes of unrelated, untouched skills.
- **Parameter-creation count is no longer inflated by already-existing parameters.** `createMissingSkillParameters` incremented its counter (and logged "Created skill parameter") even when the platform answered "already exists", which spuriously triggered a follow-up `updateSkill` call. Count and log now happen only on successful creation.
- **`isAlreadyExistsApiError` no longer throws on `null`/`undefined` errors** (optional chaining on `.response`), which previously masked the original failure inside catch handlers.
- **`skillMetadataDiffers` no longer flags every skill as changed.** The model comparison used `JSON.stringify`, which is key-order-sensitive: the project map stores `{provider_idn, model_idn}` (platform API order) while YAML-built metadata uses `{model_idn, provider_idn}`. Verified against a live account: every push rewrote all 1342 skills. Model is now compared field-by-field and parameters are compared order-insensitively (sorted by name).
- **Skill parameters are now created explicitly after `createSkill`.** The platform's create endpoint ignores inline `parameters` in the request body (verified against the live platform) — newly created skills silently lost their YAML-declared parameters. The create path now calls `POST /flows/skills/{skillId}/parameters` per parameter, same as the update path.

## [3.7.3] - 2026-05-25

### Fixed

- **Workflow Builder canvas blank-screen, take two** - JSON-typed attribute values that contain Markdown body text with `\_` escapes (Builder uses backslash-underscore to escape underscores) and/or structural newlines from pretty-printed JSON no longer corrupt the canvas on push. Two bugs were leaking through v3.7.1's STRING-coercion fix: (a) `yaml.dump` of a pretty-printed JSON string emitted a double-quoted scalar with `\n` escape sequences, which `patchYamlToPyyaml` then rewrote as a single-quoted scalar where `\n` became two literal chars - Builder's `JSON.parse` then choked on backslash-n as structural whitespace; (b) `\_` is not a valid JSON escape per RFC 8259 and Chrome V8's `JSON.parse` throws on it, silently blanking the Builder. Fix: `normalizeJsonValueForStorage` now strips invalid escape sequences via a quote-aware walker (`fixInvalidJsonEscapes`), then compacts via `JSON.parse` + `JSON.stringify` so the value is a single-line string that survives `yaml.dump` -> `patchYamlToPyyaml` without escape-sequence corruption. Existing pretty-printed canvases in `attributes.yaml` will be reformatted to compact form on next pull (one-time stylistic diff, no semantic loss). Change-detection (`jsonValuesEqual`) continues to canonicalize both sides so the new compact form does not trigger spurious pushes against remotes that may still be pretty. Reported by Bob in [#7](https://github.com/sabbah13/newo-cli/pull/7); 25 regression tests in `test/json-attribute-roundtrip.test.js` covering both bug families and the full pull -> dump -> patch -> reload -> `JSON.parse` pipeline.

### Added

- **`fixInvalidJsonEscapes(s)`** in `src/sync/json-attr-utils.ts` - quote-aware walker that strips invalid JSON escape sequences (`\_`, `\.`, etc.) inside JSON string values per RFC 8259. Preserves all valid escapes (`\" \\ \/ \b \f \n \r \t \uXXXX`) and structural characters outside strings.

## [3.7.2] - 2026-05-17

### Fixed

- **`newo push` now syncs flow metadata (title, events, state_fields) to the platform** — closes [#3](https://github.com/sabbah13/newo-cli/issues/3). Previously `newo push` only uploaded skill scripts; edits to a flow's `metadata.yaml` (V1) or `{FlowIdn}.yaml` (V2) silently never reached the platform, and events added via `newo create-event` could appear to disappear after a subsequent push because the local-side definition lagged the remote one. Push now performs hash-gated reconciliation per flow: when `metadata.yaml` changes locally it calls `PATCH /api/v1/designer/flows/{id}` for title/description/runner, then create/update/delete child events and state_fields against `/events` and `/states` so the platform mirrors local. Hash-gating is critical — flows whose `metadata.yaml` is untouched are never even compared, so stale local trees cannot accidentally wipe events created out-of-band via the Builder UI. Wired into the legacy `pushChanged` path, `ProjectSyncStrategy`, and `V2ProjectSyncStrategy`. Reported by Bob (issue #3).

### Added

- **`updateFlow`, `updateFlowEvent`, `updateFlowState`, `deleteFlowState`, `getFlow` API wrappers** in `src/api.ts` for the previously-undocumented `PATCH /api/v1/designer/flows/{id}`, `PATCH /api/v1/designer/flows/events/{id}`, `PUT /api/v1/designer/flows/states/{id}`, `DELETE /api/v1/designer/flows/states/{id}`, and `GET /api/v1/designer/flows/{id}` endpoints. Empty payload returns 500; the platform requires the full descriptor.
- **`src/sync/flow-metadata.ts`** module — pure-logic reconciler shared by both V1 and V2 push paths. Comparator helpers `flowEventDiffers`/`flowStateDiffers` normalize null/undefined/empty so YAML round-trips don't trigger spurious updates.
- **18 unit tests** in `test/flow-metadata.test.js` covering create/update/delete event flows, state CRUD in a single pass, no-op when local matches remote, and graceful error handling that records failures without aborting the loop.

## [3.7.1] - 2026-04-29

### Fixed

- **Workflow Builder canvas blank-screen after `newo push --only attributes`** - JSON-typed project/customer attributes (e.g. `project_attributes_private_dynamic_workflow_builder_canvas`) are now always coerced to a JSON STRING when persisted to `attributes.yaml` and when sent on push. Previously, when the API returned the `value` field as a parsed object, `yaml.dump` serialized it as a YAML structure and the next push sent `{"value": {...object...}}` instead of `{"value": "...json..."}` - the platform stored a shape Builder could not render and the canvas blanked out. Change-detection now compares both sides as canonical (compact) JSON, so pretty- vs compact-printed forms and string vs object representations no longer trigger spurious pushes. String-typed values are left bit-for-bit untouched, so no churn on existing repos. New helpers in `src/sync/json-attr-utils.ts` are wired into both `src/sync/attributes.ts` and `src/domain/strategies/sync/AttributeSyncStrategy.ts`. Reported by Bob; 19 regression tests in `test/json-attribute-roundtrip.test.js`.

## [3.7.0] - 2026-04-23

### Added

- **`newo lint` command** - Static analysis for Guidance / Jinja / NSL / NSLG files. Exit codes 0/1/2. Flags: `--format`, `--reporter text|json|sarif`, `--max-warnings`, `--quiet`, `--rule`, `--rule-off`, `--changed`, `--live`, `--customer`. Powered by `newo-dsl-analyzer`, the same engine used by the VS Code extension.
- **`newo format` command** - Apply canonical formatting in place. `--check` flag reports without writing (CI gate). v1 is an identity transform that ensures final newline; concrete formatting rules iterate in later releases.
- **`newo check` command** - Umbrella command: runs `lint` then `format --check` for a single CI gate invocation.
- **`src/lint/` glue module** - File discovery respecting format-aware extensions and `.newo/{customer}/hashes.json` for `--changed`, `.neworc.yaml` config loader, live schema refresh (caches `/api/v1/script/actions` response to `.newo/{customer}/actions.json`), text/JSON/SARIF 2.1.0 reporters.
- **Dependency on `newo-dsl-analyzer` and `newo-dsl-core`** - the shared Newo DSL analysis engine published from the newo-nsl-lsp repo. See README for the plugin contract.
- **Offline mode for lint/format/check** - These commands do not require `NEWO_API_KEY` or any environment configuration when run with explicit paths and without `--customer` or `--live`. Safe for pre-commit hooks and sandboxed CI jobs.
- **`.neworc.yaml` config discovery** - Walks up the directory tree from cwd to find lint config. Supports `rules`, `plugins`, `extensions`, `ignore`.

### Changed

- `src/cli.ts` short-circuits environment validation for offline `newo lint` / `newo format` / `newo check` invocations. All other commands still require credentials at startup.

### Publisher notes

Before running `npm publish` on this version, swap the local `file:` dependencies in `package.json` for semver ranges (npm rejects published packages that reference `file:` paths). The `newo-dsl-*` packages must be published from the [newo-nsl-lsp](https://github.com/newo-ai/newo-nsl-lsp) monorepo first:

```json
"dependencies": {
  "newo-dsl-analyzer": "^1.0.0",
  "newo-dsl-core": "^1.0.0",
  ...
}
```

Recommended release order:
1. Tag `v1.0.0` on newo-nsl-lsp -> CI publishes `newo-dsl-core`, `newo-dsl-data`, `newo-dsl-analyzer`, `newo-dsl-lsp` to npm.
2. In newo-cli: swap `file:` to `^1.0.0`, `npm install`, build, test.
3. Tag `v3.7.0` on newo-cli -> `npm publish --access public`.

## [3.6.2] - 2026-04-23

### Fixed

- **`attributes.yaml` YAML escaping** - Values containing double quotes (e.g. `["+37410333310"]`) are now serialized as single-quoted scalars instead of invalid double-quoted output. Previously `newo push --format newo_v2` could not parse round-tripped files because the generated YAML was malformed. Fix ported via PR #1 (commit `d3a1d4e`).

## [3.6.1] - 2026-04-14

### Documentation

- Update README.md with V2 format, libraries, and `newo export` documentation for npm package page

## [3.6.0] - 2026-04-13

### Added

- **NEWO V2 Format Support** - Dual format support: `cli_v1` (native, default) and `newo_v2` (NEWO platform import/export compatible). Format is auto-detected per customer from filesystem (`import_version.txt` = newo_v2, `projects/` dir = cli_v1). Multiple formats coexist in the same workspace.
- **Libraries** - New entity type for shared reusable skills across agents within a project. Full pull/push/status support in both cli_v1 and newo_v2 formats via `GET/POST /api/v1/designer/projects/{id}/libraries` and `PATCH /api/v1/designer/libraries/{id}/skills/{id}`.
- **`newo export` command** - Bulk download V2 export ZIP from NEWO platform via `POST /api/v2/designer/customer/export`. Usage: `newo export [--output file.zip] [--customer idn]`.
- **`--format` flag** - Per-command format override for `pull`, `push`, and `status` commands. Values: `cli_v1`, `newo_v2`.
- **`NEWO_FORMAT` environment variable** - Persistent default format for new pulls (only affects customers without existing local files).
- **Format auto-detection** - Automatic per-customer format detection from filesystem markers. Existing projects always auto-detect; env var only applies to fresh pulls.
- **V2ProjectSyncStrategy** - New sync strategy using same V1 APIs but writing newo_v2 file layout (agents/flows/skills structure, .nsl/.nslg extensions, inline flow YAML with skills/events/states).
- **Format module** (`src/format/`) - Types, detection, extension mapping, V2 paths, V2 YAML parsers/generators, and pyyaml-compatible formatting.

### Changed

- `pull`, `push`, and `status` commands now support `--format` flag and auto-detect format per customer
- DI bootstrap conditionally registers V2ProjectSyncStrategy when format is newo_v2
- `skill-files.ts` now recognizes `.nslg` extension alongside `.guidance`, `.jinja`, `.nsl`
- `env.ts` validates `NEWO_FORMAT` environment variable
- API client factory passes customer config to `getValidAccessToken()` for correct multi-customer auth

## [3.4.2] - 2026-04-12

### Added

- **`newo update-attribute` command**: Update existing customer attributes by IDN. Supports `--value`, `--title`, `--description`, `--group`, `--hidden`, `--value-type`, and `--possible-values` flags. Only explicitly provided fields are overridden; unspecified fields retain their current values.

### Fixed

- **`create-attribute --value 0`**: Fixed a bug where numeric zero values passed via `--value 0` were incorrectly rejected as "value required". The minimist argument parser returns numeric `0` which was treated as falsy by the `||` operator. Now uses explicit `undefined` check.

## [3.4.1] - 2026-04-12

### Fixed

- **Token refresh on 403 responses**: The HTTP client interceptor now handles both 401 and 403 status codes when retrying with a fresh token. Previously, only 401 triggered automatic token re-authentication, but the NEWO API returns 403 ("Invalid token or expired token") for expired JWTs. This caused long-running operations like `newo conversations --all` to fail mid-download on accounts with large datasets (50,000+ conversations) where pagination exceeds the 15-minute token lifetime.

## [3.4.0] - 2025-12-25

### Added

- **Project Registry**: Browse and install project templates from NEWO registries
  - `newo list-registries` - List available registries (production, staging, development, etc.)
  - `newo list-registry-items <registry-idn>` - Browse project templates in a registry with version info
  - `newo add-project <idn> --item <template-idn>` - Install project from registry template
  - Support for multiple registries: production, staging, development, testing, and custom registries
  - Version selection with `--version` flag or automatic latest version detection
  - Auto-update support with `--auto-update` flag for automatic updates when new versions are published
  - Grouped display showing unique projects with version counts and active installations
  - `--all` flag to show all versions of each project template

- **Registry Types** (`src/types.ts`):
  - `Registry` - Registry metadata (id, idn, account_id, is_public)
  - `RegistryItem` - Project template with versioning (id, idn, version, project_image, active_project_count)
  - `RegistryItemProjectImage` - Project image metadata for templates
  - `AddProjectFromRegistryRequest` - Request type for registry-based project installation

- **Registry API Functions** (`src/api.ts`):
  - `listRegistries()` - Fetch available registries
  - `listRegistryItems()` - Fetch project templates from a specific registry
  - `addProjectFromRegistry()` - Create project from registry template

- **Registry Command Handlers** (`src/cli/commands/`):
  - `list-registries.ts` - Display registries in formatted table
  - `list-registry-items.ts` - Display projects with version grouping and sorting
  - `add-project.ts` - Install templates with validation and progress feedback

### Enhanced

- **Help Command**: Added registry commands documentation and examples
- **CLAUDE.md**: Updated with registry feature documentation, API endpoints, and data flow

## [3.3.0] - 2025-10-20

### Added

- **Account Migration System**: Fully automated account copying from source to destination
  - `newo migrate-account` - Complete migration command with progress tracking
  - Automatic webhook creation from YAML configuration files
  - API mapping built from live API queries to prevent content loss
  - Comprehensive migration includes all entities: projects, agents, flows, skills, attributes, AKB, integrations, connectors, webhooks
  - Interactive confirmation with multi-stage progress indicators
- **Migration Verification**: Compare entity counts between source and destination accounts
  - `newo verify` - Verification command showing detailed entity comparison
  - Entity count validation for projects, agents, flows, and skills
  - SHA256 checksum verification for file integrity
  - Webhook existence verification
- **Webhook Creation**: Direct webhook creation from YAML files
  - `newo create-webhooks` - Batch webhook creation command
  - Support for both outgoing and incoming webhook types
  - YAML-based configuration with automatic detection
- **Migration Module** (`src/sync/migrate.ts`):
  - Complete migration orchestration logic
  - API mapping generation from live queries
  - Webhook creation automation
  - Progress tracking and error handling
- **Enhanced API Functions**:
  - `updateProject()` - Update project metadata on platform
  - `updateAgent()` - Update agent metadata on platform
  - `createOutgoingWebhook()` - Create outgoing webhooks via API
  - `createIncomingWebhook()` - Create incoming webhooks via API

### Enhanced

- **Pull Command**: Deletion detection for entities removed remotely
  - Interactive confirmation before deleting local entities
  - Confirmation options: y (yes), n (no), a (all), q (quit)
  - Prevents accidental deletion of local work
  - Graceful handling of remote entity removal
- **Status Command**: Full path display in error messages
  - Complete paths shown: project/agent/flow/skill hierarchy
  - Improved debugging with clear file location information
- **Type Definitions**: Extended for enhanced metadata support
  - `Agent.persona` field for persona association
  - `ProjectMeta` fields: `is_auto_update_enabled`, `registry_idn`, `display_idn`, `svc_catalog_slug`
  - Enhanced event creation metadata: `skill_selector`, `interrupt_mode`, `skill_idn`, `connector_idn`
- **Help Command**: Updated documentation for migration commands
  - Complete migration workflow documentation
  - Verification command usage examples
  - Webhook creation command reference

### Fixed

- **Pull Command**: No longer overwrites local files with empty API content
  - Protection against data loss from API errors
  - Validation of API response before writing files
  - Skip empty content writes with warning messages
- **Event Creation**: Full metadata preservation from source
  - Event skill_selector properly copied
  - Interrupt mode settings preserved
  - Skill and connector IDN associations maintained
- **Migration Script**: Proper map.json generation from API
  - Builds ID mappings directly from API queries
  - No longer depends on pull command execution
  - Ensures accurate entity relationships

### Testing

- **Complete Account Migration**: Successfully migrated account with 1,084 skills
  - Tested across 3 different test accounts
  - 100% entity match validation (projects, agents, flows, skills)
  - 100% file integrity verification (SHA256 checksums on attributes)
  - 100% webhook creation success (all 5 webhooks verified)
  - Significant time reduction compared to manual migration process
- **Entity Count Verification**: Automated comparison validates all entity types
- **Webhook Creation**: Batch webhook creation from YAML files tested and verified

### Performance

- **Migration Automation**: 100% automated with zero manual steps required
- **Reliability**: 100% success rate across multiple test migrations
- **Data Integrity**: Full SHA256 verification ensures zero data loss

## [3.2.0] - 2025-10-17

### Added

- **Integration Management**: Complete integration and connector management system
  - `newo pull-integrations` - Download all integrations, connectors, and webhooks to local YAML files
  - `newo push-integrations` - Upload connector changes with full CRUD support (Create, Update, Delete)
  - Combined integration files: `{integration_idn}.yaml` contains metadata + settings in single file
  - Nested connector structure: Each connector in own subdirectory `connectors/{connector_idn}/{connector_idn}.yaml`
  - Automatic webhook synchronization (outgoing + incoming webhooks)
  - 15 integrations discovered and managed (api, sandbox, twilio, magic_browser, newo_chat, etc.)
  - Full connector lifecycle: Create via YAML + push → Modify → Delete via YAML removal + push
- **AKB Knowledge Base Management**: Complete knowledge base synchronization
  - `newo pull-akb` - Download AKB articles for all personas linked to agents
  - `newo push-akb` - Upload AKB articles from local YAML files to platform
  - YAML format matches backup structure exactly for compatibility
  - Automatic persona-to-agent mapping via agent IDN
  - Pagination support for large knowledge bases
  - Articles stored in `akb/{agent_idn}.yaml` format
- **Project Attributes**: Full project-level attribute management
  - Enhanced `newo pull-attributes` to pull both customer AND project attributes
  - Project attributes saved to `projects/{project_idn}/attributes.yaml`
  - Push integrated into main `newo push` command
  - Automatic ID mapping for push operations
  - Same YAML format as customer attributes with !enum tags
  - Change detection and update mechanism
- **Developer Tools**: Reference and productivity features
  - `newo list-actions` - List all 78 available NSL/Jinja script actions with categorization
  - `newo profile` - Display customer profile information (organization, email, platform links)
  - Action categorization into 12 groups (Gen, Get, Create, Delete, Update, etc.)
  - Verbose mode shows complete parameter schemas for each action
- **API Integrations**: 17 new API endpoints
  - Integration endpoints: GET integrations, connectors, settings
  - Connector CRUD: POST, PUT, DELETE for connectors
  - Webhook endpoints: GET outgoing/incoming webhooks
  - AKB endpoints: GET personas, topics; POST import
  - Project attribute endpoints: GET, PUT for project attributes
  - Script actions endpoint: GET all NSL actions
  - Customer profile endpoint: GET profile information
- **TypeScript Types**: 22 new interfaces for complete type safety
  - Integration types: Integration, Connector, IntegrationSetting, CreateConnectorRequest, UpdateConnectorRequest
  - Webhook types: OutgoingWebhook, IncomingWebhook
  - AKB types: Persona, AkbTopic, AkbTopicItem, AkbYamlTopic
  - Script action types: ScriptAction, ArgumentSchema
  - Metadata types: IntegrationMetadata, ConnectorMetadata, IntegrationsYamlData

### Changed

- **File Structure**: Enhanced directory hierarchy with new integration and AKB folders
  - `newo_customers/{customer}/integrations/` - Integration configurations
  - `newo_customers/{customer}/akb/` - AKB knowledge base articles
  - `newo_customers/{customer}/projects/{project}/attributes.yaml` - Project attributes
- **Pull Attributes Command**: Now pulls both customer and project attributes in single command
- **Push Command**: Enhanced to push project attribute changes alongside skill changes
- **Help Documentation**: Comprehensive updates with all new commands and file structure
- **Integration Structure**: Nested connector directories with webhook subdirectories
  - `integrations/{integration}/{integration}.yaml` - Combined metadata + settings
  - `integrations/{integration}/connectors/{connector}/{connector}.yaml` - Connector config
  - `integrations/{integration}/connectors/{connector}/webhooks/` - Webhook files

### Technical Details

- **Modular Architecture**: 8 new modules created
  - `src/sync/integrations.ts` (340+ lines) - Integration/connector/webhook sync
  - `src/sync/akb.ts` (205 lines) - AKB knowledge base sync
  - `src/cli/commands/pull-integrations.ts` - Integration pull handler
  - `src/cli/commands/push-integrations.ts` - Integration push handler
  - `src/cli/commands/pull-akb.ts` - AKB pull handler
  - `src/cli/commands/push-akb.ts` - AKB push handler
  - `src/cli/commands/list-actions.ts` - Script actions listing
  - `src/cli/commands/profile.ts` - Profile viewer
- **Enhanced Modules**: 6 existing modules updated
  - `src/types.ts` (+160 lines) - New type definitions
  - `src/api.ts` (+110 lines) - New API functions
  - `src/sync/attributes.ts` (+126 lines) - Project attribute support
  - `src/sync/push.ts` (+15 lines) - Project attribute push integration
  - `src/cli.ts` (+12 lines) - New command routing
  - `src/cli/commands/help.ts` (+30 lines) - Documentation updates
- **Webhook Association**: Webhooks grouped by connector_idn and stored in connector subdirectories
- **Change Detection**: Smart comparison for connectors (title, status, settings)
- **Error Handling**: Graceful handling of missing settings endpoints (404 errors)
- **ID Mapping**: Separate JSON files for attribute ID mappings to enable push operations
- **YAML Parsing**: Custom !enum tag handling for AttributeValueTypes

### Example Usage

```bash
# Integration management
newo pull-integrations                    # Download all integrations + webhooks
newo push-integrations                    # Upload connector changes

# Knowledge base management
newo pull-akb                             # Download AKB for personas with agents
newo push-akb                             # Upload AKB articles

# Enhanced attributes
newo pull-attributes                      # Now pulls customer + project attributes
newo push                                 # Now pushes project attributes too

# Developer tools
newo profile                              # View customer information
newo list-actions                         # Browse 78 NSL actions
newo list-actions --verbose               # With parameter details
```

### Files Created

**Integration Structure:**
```
newo_customers/{customer}/integrations/
├── integrations.yaml
└── {integration_idn}/
    ├── {integration_idn}.yaml           # Combined metadata + settings
    └── connectors/
        └── {connector_idn}/
            ├── {connector_idn}.yaml
            └── webhooks/
                ├── outgoing.yaml
                └── incoming.yaml
```

**AKB Structure:**
```
newo_customers/{customer}/akb/
└── {agent_idn}.yaml                     # AKB articles per agent
```

**Project Attributes:**
```
newo_customers/{customer}/projects/{project}/
└── attributes.yaml                      # Project-specific attributes
```

### Breaking Changes

None. All changes are additive and backward compatible.

## [3.1.0] - 2025-10-15

### Added

- **Sandbox Chat Testing**: Real-time agent testing with interactive sandbox mode
  - `newo sandbox "<message>"` - Single-command mode for automated testing workflows
  - `newo sandbox --actor <id> "message"` - Multi-turn conversation continuation
  - Automatic persona/actor creation with unique naming (`newo-cli-{guid}`)
  - Chat History API polling with 1-second intervals, 60-second timeout
  - Debug information extraction (flow_idn, skill_idn, session_id, runtime_context_id)
  - Quiet mode (`--quiet`/`-q`) for script-friendly output with minimal logging
  - Single newest message display to avoid overwhelming output
- **Sandbox API Integration**: 6 new endpoints for sandbox chat functionality
  - `GET /api/v1/integrations` - List available integrations
  - `GET /api/v1/integrations/{id}/connectors` - List integration connectors
  - `POST /api/v1/customer/personas` - Create user persona for sandbox testing
  - `POST /api/v1/customer/personas/{id}/actors` - Create actor (chat session)
  - `POST /api/v1/chat/user/{actorId}` - Send chat message
  - Reused `GET /api/v1/chat/history` - Poll for agent responses with timestamp filtering
- **Sandbox Utilities Module** (`src/sandbox/chat.ts`):
  - `findSandboxConnector()` - Locate running sandbox connectors
  - `createChatSession()` - Initialize new chat sessions with unique personas
  - `sendMessage()` - Send messages with timestamp tracking for response filtering
  - `pollForResponse()` - Intelligent polling with timestamp-based message filtering
  - `extractAgentMessages()` - Filter and extract agent responses from chat history
  - `formatDebugInfo()` - Format debug information for developer inspection
- **TypeScript Types**: Comprehensive type definitions for sandbox functionality
  - `Integration`, `Connector` - Integration and connector management
  - `SandboxChatSession` - Session state tracking with persona/actor IDs
  - `ChatDebugInfo` - Debug information structure for agent development
  - `CreateSandboxPersonaRequest/Response` - Persona creation types
  - `CreateActorRequest/Response` - Actor creation types
  - `SendChatMessageRequest` - Chat message sending types
- **Enhanced Authentication**: Quiet mode support to suppress logging during automated testing
- **Documentation**: Comprehensive sandbox testing section with usage examples and automation patterns

### Changed

- **CLI Architecture**: Added sandbox command routing in main CLI module
- **API Module**: Extended with sandbox-specific endpoint integrations
- **Help Command**: Updated with sandbox command reference
- **README**: Added extensive sandbox testing documentation with multi-turn examples (+101 lines)

### Technical Details

- **Message Filtering**: Timestamp-based filtering ensures only new messages shown after user sends message
- **Session Isolation**: Each sandbox test creates unique persona with GUID to prevent state interference
- **Polling Strategy**: 1-second intervals with 60-second max wait for agent responses
- **Error Handling**: Graceful degradation with timeout messages and continuation guidance
- **Debug Modes**: Standard (condensed) and verbose (detailed) debug information display
- **Quiet Mode**: Minimal output perfect for shell scripts and CI/CD integration

### Example Usage

```bash
# Start new conversation
newo sandbox "Hello, I want to order pizza"

# Continue conversation with actor ID from previous response
newo sandbox --actor abc123... "I want 2 large pepperoni pizzas"

# Verbose mode for debugging
newo sandbox "Test message" --verbose

# Quiet mode for automation
newo sandbox "Test query" --quiet
```

## [3.0.0] - 2025-09-29

### Added

- **Entity Creation Commands**: 12 new commands for creating NEWO entities locally
  - `newo create-project <idn>` - Create new projects on platform
  - `newo create-persona <name>` - Create agent personas
  - `newo create-attribute <idn>` - Create customer attributes
  - `newo create-agent <idn> --project <pid>` - Create agents locally with metadata
  - `newo create-flow <idn> --agent <aid>` - Create flows with guidance/NSL runner selection
  - `newo create-skill <idn> --flow <fid>` - Create skills with script content initialization
  - `newo create-event <idn> --flow <fid>` - Create flow events for integrations
  - `newo create-state <idn> --flow <fid>` - Create flow state fields (user/flow/global scope)
  - `newo create-parameter <name> --skill <sid>` - Create skill parameters
- **Entity Deletion Commands**: 3 new commands with confirmation flags
  - `newo delete-agent <aid> --confirm` - Delete agent locally
  - `newo delete-flow <fid> --confirm` - Delete flow locally
  - `newo delete-skill <sid> --confirm` - Delete skill locally
- **API Integrations**: 19 new endpoints for entity creation, deletion, and publishing
- **Documentation**: Entity Management Commands section with workflows and examples (+146 lines)
- **TypeScript Types**: 19 new type definitions for entity operations

### Changed

- **Push Command**: Now automatically detects and creates local-only entities on platform
  - Filesystem scanning for entities not yet in project map
  - Creates missing entities in correct hierarchical order (agent → flow → skill)
  - Publishes flows after creation
- **Status Command**: Enhanced with comprehensive change detection
  - Scans for local-only entities not yet on platform
  - Reports new agents/flows/skills awaiting sync
  - Hierarchical display of project structure
- **Architecture**: Added 14 new command modules in src/cli/commands/
- **Push Module**: Enhanced with local-only entity scanning (~418 lines)
- **Status Module**: Enhanced with entity detection (~184 lines)

## [2.0.6] - 2025-09-18

### Changed

- Implement proper LCS-based diff algorithm for accurate change detection
- Clean, accurate differences with proper line matching
- Improved algorithm eliminates false positives and shows precise modifications

## [2.0.5] - 2025-09-18

### Fixed

- Correct diff algorithm to show clean, accurate differences
- Improved change detection with proper context preservation

## [2.0.4] - 2025-09-18

### Changed

- Implement exact GitHub diff format with proper context lines
- GitHub-style diff with background colors and context
- Enhanced diff display with line numbers and clearer messaging

## [2.0.3] - 2025-09-18

### Changed

- Improve diff display with line numbers and clearer messaging
- Better visual distinction for changes with colored output

## [2.0.2] - 2025-09-18

### Added

- GitHub-style colored diff display for overwrite prompts
- Enhanced diff visualization with colors and formatting

## [2.0.1] - 2025-09-18

### Fixed

- Improve overwrite handling with proper 'all' option support
- Better handling of batch overwrite operations

## [1.9.3] - 2025-09-17

### Changed

- **BREAKING**: Main CLI entry point moved from `dist/cli.js` to `dist/cli/index.js`
- Split monolithic 500+ line `cli.ts` into focused modules
  - `cli/index.ts` - Main entry point and command routing
  - `cli/errors.ts` - Centralized error handling
  - `cli/customer-selection.ts` - Customer management logic
  - `cli/commands/` - Individual command handlers
- Extracted key functions from 1400+ line `sync.ts` into focused modules
  - `sync/attributes.ts` - Customer attributes synchronization
  - `sync/conversations.ts` - Conversation history management
  - `sync/status.ts` - File status checking and change detection
  - `sync/index.ts` - Unified exports with backward compatibility
- Updated CLAUDE.md with new modular architecture documentation

### Fixed

- Test imports to use compiled JavaScript from `dist/` directory
- Test utilities converted from CommonJS to ES modules
- Improved test isolation and ES module compatibility

## [2.0.0] - 2025-09-17

### Added

- IDN-based skill file naming for easy identification
- Real-time progress display during large operations (966+ skills)
- Percentage completion with skill counts
- Multiple file detection with clear warnings
- Force mode with `--force/-f` flag for silent operations
- Complete metadata.yaml hierarchy at all levels

### Changed

- **BREAKING**: Skills now saved as `{skillIdn}.jinja/.guidance` instead of `skill.jinja/.guidance`
- **BREAKING**: Existing files automatically renamed to IDN format during pull
- Refactored CLI module structure
  - `src/cli.ts` (124 lines) - Clean main entry using modular imports
  - `src/cli/errors.ts` - Centralized error management
  - `src/cli/customer-selection.ts` - Reusable customer selection logic
  - `src/cli/commands/` - Individual handlers for all commands
- Refactored sync module structure
  - `src/sync.ts` (13 lines) - Unified exports with re-exports
  - `src/sync/projects.ts` - Project sync with progress tracking
  - `src/sync/push.ts` - File validation and upload
  - `src/sync/status.ts` - Change detection with file validation
  - `src/sync/attributes.ts` - Customer attributes synchronization
  - `src/sync/conversations.ts` - Conversation history management
  - `src/sync/metadata.ts` - flows.yaml generation (removed prompt_script)
  - `src/sync/skill-files.ts` - IDN-based naming and validation
- Flexible file discovery (any .jinja/.guidance/.nsl file)
- Smart overwrite detection (content-based, not filename-based)
- Complete hash coverage for flows.yaml and attributes.yaml
- Zero TypeScript compilation errors with strict typing
- Modular loading with reduced memory footprint

### Fixed

- False positive change detection
- Status now shows "Clean." immediately after pull operations
- Safe push operations that skip problematic skills with multiple files

## [1.9.2] - 2025-09-16

### Added

- Max pages limit (50 pages = 5000 acts per persona) to prevent infinite pagination
- Verbose logging for pagination progress

### Changed

- Skip personas without newo_voice actors immediately for better performance
- Optimized control flow to prevent hanging during large conversation extraction

### Fixed

- Infinite loops during conversation processing
- Improved persona filtering for voice actors
- Graceful handling of personas without voice actors

## [1.9.1] - 2025-09-16

### Removed

- Conversations acts API fallback (eliminates 403 errors)
- `getConversationActs()` function (unused after chat history integration)
- `ConversationActsParams` and `ConversationActsResponse` interfaces
- Fallback logic that caused 403 errors for personas without proper permissions

### Changed

- Use only `/api/v1/chat/history` endpoint which works with current API keys

## [1.9.0] - 2025-09-16

### Added

- `newo conversations` command to download user conversations and personas
- Multi-customer conversation support with `--customer <idn>` flag
- Chat History API integration (`/api/v1/chat/history`) with fallback support
- Automatic phone number extraction from persona actors
- Comprehensive pagination handling for large conversation datasets
- Clean YAML output format in `newo_customers/{customerIdn}/conversations.yaml`
- Type-safe conversation API integration
  - `listUserPersonas()` - Get all user personas with pagination
  - `getChatHistory()` - Get conversation history for user actors
  - `getConversationActs()` - Fallback for accounts with proper permissions
  - `pullConversations()` - Complete conversation sync orchestration
- NPM scripts: `npm run conversations` and `npm run conversations:all`

### Changed

- Acts sorted by datetime ascending (chronological conversation flow)
- Personas sorted by most recent activity (descending)
- Clean persona structure: `id` → `name` → `phone` → `act_count` → `acts`
- Parallel API calls with concurrency limiting (p-limit)
- Graceful error handling with persona-level fault tolerance

### Removed

- Redundant fields (`is_agent`, `session_id: unknown`, etc.)

## [1.8.0] - 2025-09-15

### Added

- Complete metadata.yaml file synchronization with hash-based change detection
- Status command shows detailed metadata changes (title, runner_type, model)
- Push command automatically updates skills when metadata changes
- Automatic flows.yaml regeneration when metadata changes detected
- flows.yaml backup/comparison system for format preservation

### Changed

- All NEWO workspace files fully tracked
  - Skills: .guidance and .jinja script files with hash tracking
  - Metadata: metadata.yaml files with skill updates + flows.yaml regeneration
  - Attributes: attributes.yaml with diff-based sync for 233 customer attributes
  - Flows: flows.yaml with automatic regeneration and format preservation
  - Multi-customer: All file types synchronized across multiple customer workspaces
- Automatic regeneration pipeline creates backup before regeneration
- Re-fetches project data to ensure accuracy
- Maintains consistent YAML format structure

## [1.7.3] - 2025-09-15

### Added

- Full hash-based change detection for customer attributes
- Attributes.yaml files included in hash tracking during pull operations
- Status command detects and reports modifications to attributes.yaml files
- Push command handles attributes changes with proper synchronization

### Changed

- Extended file synchronization scope to all NEWO workspace file types
  - Skills: .guidance and .jinja files with full hash tracking
  - Attributes: customer attributes.yaml with change detection
  - Metadata: flows.yaml and metadata.yaml files tracked
  - Multi-customer: all file types synchronized across multiple customers

## [1.7.2] - 2025-09-15

### Added

- `attributes.yaml` file tracking with modification times and sizes
- `flows.yaml` file tracking and statistics
- Comprehensive file monitoring across entire project structure

### Fixed

- Attributes push check error with `!enum` format
- Changed from YAML parsing to file stats for change detection
- Prevents parsing errors with custom enum format in attributes.yaml

## [1.7.1] - 2025-09-15

### Changed

- `newo status` now automatically checks all customers when no default is specified
- `newo push` provides interactive customer selection dialog when multiple customers exist
- Moved customer selection logic into command-specific handlers
- Each command now handles customer selection appropriately

### Fixed

- Early exit errors for multi-customer operations
- Maintains backward compatibility with single-customer setups

## [1.7.0] - 2025-09-15

### Added

- Complete pull/push functionality for customer attributes
- `GET /api/v1/bff/customer/attributes?include_hidden=true` endpoint integration (fetches 233 attributes)
- `PUT /api/v1/customer/attributes/{attributeId}` endpoint integration
- Saves to `newo_customers/{customerIdn}/attributes.yaml` in customer root directory
- YAML format with literal blocks, enum types, and proper multi-line formatting
- Separate ID mapping in `.newo/{customerIdn}/attributes-map.json` for push operations
- Full TypeScript type safety with `CustomerAttribute` and `CustomerAttributesResponse` interfaces
- API layer functions: `updateCustomerAttribute()` and enhanced `getCustomerAttributes()`
- File system utilities: `customerAttributesPath()` and `customerAttributesMapPath()`

### Changed

- Integrated attributes handling into existing `pull` and `push` commands
- YAML format compliance with reference specification
  - Literal block scalars (`|-`) for multi-line strings
  - Proper enum format (`!enum "AttributeValueTypes.string"`)
  - Complex JSON string formatting with proper line breaks
  - No escaped quotes in output

### Removed

- Legacy JSON metadata files (YAML-only approach)
- Redundant `metadata.json` files

## [1.6.1] - 2025-09-13

### Added

- `"type": "module"` to package.json for proper ES module handling

### Fixed

- Enum formatting in `flows.yaml` generation for NEWO enum types
- Enum value serialization from quoted strings to proper YAML enum format
- Issue where enum values like `!enum "RunnerType.guidance"` were incorrectly quoted

## [1.6.0] - 2025-09-13

### Added
- **Multi-Customer Auto-Pull**: Revolutionary workflow improvement for multi-customer environments
  - `newo pull` now automatically pulls from ALL customers when no default customer is set
  - Eliminates the need to specify `--customer` flag or set `NEWO_DEFAULT_CUSTOMER` for bulk operations
  - Maintains backward compatibility - individual customer selection still works with `--customer` flag
  - Smart detection: single customer setup works as before, multi-customer setup auto-pulls all
- **Publishing Infrastructure**: Complete automated publishing system for professional releases
  - `scripts/publish-github.sh`: Automated GitHub publishing with releases, tags, and version management
  - `scripts/publish-npm.sh`: Automated NPM publishing with validation and safety checks
  - Comprehensive Makefile with 40+ commands for development and publishing workflows
  - Version bump helpers (patch/minor/major) with semantic versioning support
- **Enhanced Documentation**: Professional publishing and development documentation
  - Complete "Publishing & Release Management" section with step-by-step workflows
  - "Local Testing" section with comprehensive testing procedures
  - Makefile command reference with organized development workflows
  - Troubleshooting guides for common development and publishing issues

### Enhanced
- **Customer Configuration Logic**: New functions for flexible customer handling
  - `tryGetDefaultCustomer()`: Non-throwing version that returns null for multi-customer scenarios
  - `getAllCustomers()`: Returns array of all configured customers for batch operations
  - Improved error handling and user feedback for customer selection scenarios
- **CLI User Experience**: Enhanced command behavior and help documentation
  - Updated help text to reflect auto-pull behavior: "uses default or all for pull"
  - Clear progress indicators for multi-customer operations
  - Better error messages and troubleshooting guidance
- **Development Workflow**: Professional development and publishing infrastructure
  - Makefile with color-coded output and comprehensive command organization
  - Automated validation pipelines for publishing (build, test, lint, typecheck)
  - Publishing scripts with safety checks and rollback procedures

### Changed
- **Pull Command Behavior**: Breaking change in multi-customer environments (improvement)
  - Previously: Required explicit customer selection or default customer configuration
  - Now: Automatically pulls from all customers when no default is set
  - Single customer setups: No change in behavior
  - Multi-customer setups: Significantly improved user experience
- **Help Documentation**: Updated command descriptions and examples
  - `newo pull` now shows "(all customers if no default)" in help text
  - Enhanced multi-customer examples with auto-pull scenarios
  - Updated usage patterns to reflect new workflow capabilities

### Developer Experience
- **Publishing Automation**: One-command publishing to both GitHub and NPM with full validation
- **Comprehensive Testing**: Enhanced local testing documentation with step-by-step procedures
- **Professional Infrastructure**: Industry-standard publishing pipeline with version management
- **Quality Gates**: Automated validation before publishing (TypeScript, linting, building, package validation)

## [1.5.2] - 2025-09-04

### Enhanced
- **Documentation Overhaul**: Complete README restructuring with professional presentation
  - Added npm, license, TypeScript, and Node.js badges for credibility
  - Enhanced project description highlighting multi-customer support capabilities
  - Visual feature bullets with emojis for improved readability and engagement
- **Multi-Customer Documentation**: Comprehensive guide for multi-customer workflows
  - Three flexible configuration methods: JSON arrays, individual env vars, mixed approaches
  - Clear migration path from single to multi-customer setup
  - Command examples for multi-customer operations (`--customer` flag usage)
- **Professional Documentation Structure**:
  - Table format for command reference with improved readability
  - Visual folder tree showing accurate `newo_customers/` structure
  - Enhanced CI/CD integration examples for both single and multi-customer scenarios
  - Contributing guidelines, API reference, and support channels
- **Corrected File Organization**: Updated folder structure documentation to match actual implementation
  - Fixed root folder from `projects/` to `newo_customers/` 
  - Accurate customer folder hierarchy: `newo_customers/{customerIdn}/projects/{projectIdn}/`
  - Customer-specific state management in `.newo/{customerIdn}/`

### Fixed
- **Folder Structure Documentation**: Corrected project structure examples to match actual code implementation
- **Package Description**: Updated npm package description to reflect multi-customer capabilities

### Developer Experience
- **GitHub/npm Ready**: Professional presentation suitable for public package repository
- **Clear Navigation**: Improved documentation structure with proper sectioning and examples
- **Enhanced Onboarding**: Comprehensive quick-start guide and configuration examples

## [1.5.1] - 2025-09-03

### Added
- **Comprehensive Test Coverage**: Added extensive test suites for all major modules
  - `test/auth.test.js`: 500+ lines covering authentication, token management, multi-customer support
  - `test/hash.test.js`: 400+ lines covering SHA256 hashing, hash storage, and cross-platform compatibility  
  - `test/fsutil.test.js`: 400+ lines covering file system utilities and path handling
  - `test/akb.test.js`: 600+ lines covering AKB article parsing and import workflows
  - Added missing test dependencies: `chai`, `sinon`, `c8` for coverage reporting
- **Enhanced Authentication Validation**:
  - `validateApiKey()`: Comprehensive API key format and length validation
  - `validateTokens()`: Token format and structure validation with detailed error messages
  - `validateUrl()`: URL format validation for API endpoints
  - Sensitive data sanitization in logs (API keys and tokens masked)
- **Structured Logging System**:
  - `logAuthEvent()`: Structured authentication event logging with metadata
  - Automatic sensitive data sanitization (keys/tokens/secrets masked in logs)
  - JSON-formatted logs with timestamp, level, module, and context information
- **Enhanced Error Handling**:
  - User-friendly CLI error messages with troubleshooting tips
  - Specific error handling for authentication, network, environment, and file system errors
  - Verbose mode support for detailed debugging information
  - Context-aware error messages with suggested solutions

### Enhanced
- **Authentication Robustness** (`src/auth.ts`):
  - Added comprehensive input validation with detailed error messages
  - Enhanced network error handling with specific status code interpretation
  - Added request timeouts (30 seconds) and retry logic for reliability
  - Improved token expiry handling with 60-second buffer for refresh
  - Better handling of connection errors, timeouts, and server errors
- **CLI Error Experience** (`src/cli.ts`):
  - Added `handleCliError()` function with categorized error types
  - User-friendly error messages with emoji indicators and troubleshooting tips
  - Verbose mode toggle for detailed technical information vs. clean user messages
  - Specific guidance for common issues (API key, network, configuration)
- **Testing Infrastructure**:
  - Fixed ES module/CommonJS compatibility issues in test files
  - Enhanced `TestEnvironment` class with comprehensive cleanup and mocking
  - Added MockHttpClient, MockFileSystem, and MockLogger utilities
  - Comprehensive assertion helpers and test data generators

### Fixed
- **Module System Compatibility**: Resolved ES module/CommonJS conflicts in test environment
- **Test Dependencies**: Added missing testing dependencies that were imported but not declared
- **Integration Test Paths**: Fixed paths from `src/cli.js` to `dist/cli.js` for proper compiled code testing
- **Error Message Consistency**: Standardized error messages across authentication and CLI modules

### Technical Details
- **Validation Constants**: Added security-focused validation thresholds (API_KEY_MIN_LENGTH, TOKEN_MIN_LENGTH)
- **Request Configuration**: Added proper timeout handling (30s) and user-agent headers
- **Error Recovery**: Comprehensive fallback strategies for different failure scenarios
- **Logging Standards**: JSON-structured logs with automatic PII/sensitive data protection
- **Test Coverage**: Achieved comprehensive test coverage across all core modules with realistic scenarios

### Developer Experience
- **Enhanced Debugging**: Verbose mode provides detailed technical information for troubleshooting
- **Better Error Messages**: Clear, actionable error messages instead of generic API errors
- **Comprehensive Testing**: Full test suite covering authentication, file operations, hashing, and AKB import
- **Type Safety**: All improvements maintain strict TypeScript compliance with proper error types

## [1.5.0] - 2025-09-03

### Changed
- **Complete TypeScript Refactoring**: Major codebase conversion from JavaScript to TypeScript
  - All source files converted to TypeScript with `.ts` extensions
  - Added comprehensive type definitions in `src/types.ts`
  - Strict TypeScript configuration with `exactOptionalPropertyTypes` and `noUncheckedIndexedAccess`
  - Modern ES2022 target with ESNext modules for optimal performance
  - Enhanced IntelliSense support and developer experience

### Added
- **TypeScript Build System**: 
  - `tsconfig.json` with strict type checking and modern ES features
  - New build scripts: `npm run build`, `npm run build:watch`, `npm run typecheck`
  - Development scripts: `npm run dev`, `npm run pull`, `npm run push`, `npm run status`
  - Source map generation for debugging compiled JavaScript
- **Enhanced Type Safety**:
  - Complete type definitions for all NEWO API responses and data structures
  - Strict error handling with proper TypeScript error types
  - Optional property handling with explicit `| undefined` types
  - Enhanced Axios integration with proper TypeScript interceptor types

### Technical Details
- **Type Definitions**: Comprehensive interfaces for `ProjectMeta`, `Agent`, `Flow`, `Skill`, `FlowEvent`, `FlowState`, and all API responses
- **Build Output**: TypeScript compiles to `dist/` directory with JavaScript and declaration files
- **Import Strategy**: Uses runtime `.js` extensions in TypeScript source (required for ESModules)
- **Dependency Updates**: Added TypeScript and @types packages for full type support
- **Package.json**: Updated with TypeScript build pipeline and development scripts

### Migration for Developers
- **New Development Workflow**: `npm run build` required before running CLI commands
- **Source Files**: All development now in `src/*.ts` files instead of `src/*.js`
- **Build Artifacts**: Generated JavaScript in `dist/` directory (automatically created)
- **IDE Support**: Enhanced autocomplete, error detection, and refactoring capabilities

### Backward Compatibility
- **Runtime Behavior**: No changes to CLI command interface or functionality
- **Environment Variables**: All existing `.env` configurations continue to work
- **File Formats**: Same `.guidance` and `.jinja` file support as before
- **API Compatibility**: No changes to NEWO API integration or endpoints

## [1.4.0] - 2025-08-20

### Added
- **Multi-Project Support**: Major feature allowing users to work with multiple NEWO projects
  - Optional `NEWO_PROJECT_ID` environment variable - if not set, pulls all accessible projects
  - New API endpoint: `GET /api/v1/designer/projects` to list all accessible projects
  - Projects stored in organized folder structure: `./projects/{project-idn}/`
  - Each project folder contains `metadata.json` with complete project information
  - Project-specific `flows.yaml` files for individual project structure exports
- **Enhanced Project Structure**:
  - Changed from single `./project/` to multi-project `./projects/{project-idn}/` hierarchy
  - Backward compatibility maintained for existing single-project workflows
  - Improved organization with project-specific metadata and flows

### Changed
- **Folder Structure**: Project files now stored in `./projects/{project-idn}/` instead of `./project/`
- **CLI Behavior**: `newo pull` now downloads all projects by default (unless NEWO_PROJECT_ID specified)
- **CI/CD Paths**: GitHub Actions workflow paths updated from `project/**/*` to `projects/**/*`
- **Help Documentation**: Updated CLI help text to reflect multi-project capabilities
- **API Integration**: Enhanced sync logic to handle both single and multi-project scenarios

### Technical Details
- **New API Functions**:
  - `listProjects()`: Fetch all accessible projects from NEWO platform
  - `pullSingleProject()`: Pull individual project with metadata generation
  - `metadataPath()`: Generate project-specific metadata file paths
- **Enhanced Sync Engine**:
  - Multi-project mapping in `.newo/map.json` with backward compatibility
  - Project-specific hash tracking for efficient change detection
  - Automatic project metadata collection and storage
- **File System Updates**:
  - Updated `fsutil.js` with multi-project path utilities
  - Enhanced `skillPath()` function to include project identifier
  - New `projectDir()` and `metadataPath()` helper functions

### Migration Guide
- **Existing Users**: Single-project setups continue to work with `NEWO_PROJECT_ID` set
- **New Users**: Leave `NEWO_PROJECT_ID` unset to access all projects automatically
- **File Paths**: Update any scripts referencing `./project/` to use `./projects/{project-idn}/`
- **CI/CD**: Update workflow paths from `project/**/*` to `projects/**/*`

### Example Usage
```bash
# Pull all accessible projects (new default behavior)
npx newo pull

# Pull specific project (original behavior)
NEWO_PROJECT_ID=your-project-id npx newo pull

# Push changes from any project structure
npx newo push

# Status works with both single and multi-project setups
npx newo status
```

## [1.3.0] - 2025-08-20

### Added
- **AKB Import Feature**: New `import-akb` command to import knowledge base articles from structured text files
  - Parse multi-article files with standardized format (separated by `---`)
  - Extract article metadata: ID, category, summary, keywords, and pricing data
  - Import articles to NEWO personas via `/api/v1/akb/append-manual` endpoint
  - Support for verbose logging with `--verbose` flag
  - Progress tracking with success/failure counts
- **Enhanced CLI**: Added `import-akb <file> <persona_id>` command with validation and error handling
- **New API Endpoint**: `importAkbArticle()` function for AKB article imports
- **Documentation**: Comprehensive AKB format documentation in README.md

### Changed
- Updated help text to include new `import-akb` command
- Enhanced CLI command parsing to handle AKB import arguments
- Updated project documentation with AKB import workflow and examples

### Technical Details
- **New Files**: 
  - `src/akb.js`: AKB file parser and article formatter
  - Article parsing supports category/subcategory structure with pricing data
- **API Integration**: 
  - Articles mapped with `topic_name` (descriptive title) and `source` (article ID)
  - Full category content stored in `topic_summary`
  - Structured metadata in `topic_facts` array
- **Error Handling**: Comprehensive validation for file paths, persona IDs, and API responses

### Example Usage
```bash
# Import AKB articles from file to specific persona
npx newo import-akb akb.txt da4550db-2b95-4500-91ff-fb4b60fe7be9

# With verbose logging
npx newo import-akb akb.txt da4550db-2b95-4500-91ff-fb4b60fe7be9 --verbose
```

### AKB File Format
```
---
# r001
## Category / Subcategory / Description
## Summary description of the category
## Keywords; separated; by; semicolons

<Category type="Category Name">
Item Name: $Price [Modifiers: modifier1, modifier2]
Another Item: $Price [Modifiers: modifier3]
</Category>
---
```

## [1.2.2] - 2025-08-12

### Changed
- Updated README with API key image
- Removed unused files and .DS_Store entries
- Package version bump

### Fixed
- Repository cleanup and organization

## [1.2.1] - Previous Release

### Added

- Initial NEWO CLI functionality
- Two-way sync between NEWO platform and local files
- Support for .guidance and .jinja file types
- SHA256-based change detection
- Project structure export to flows.yaml
- GitHub Actions CI/CD integration
- Robust authentication with token refresh

[Unreleased]: https://github.com/sabbah13/newo-cli/compare/v3.7.5...HEAD
[3.7.5]: https://github.com/sabbah13/newo-cli/compare/v3.7.4...v3.7.5
[3.7.4]: https://github.com/sabbah13/newo-cli/compare/v3.7.3...v3.7.4
[3.7.3]: https://github.com/sabbah13/newo-cli/compare/v3.7.2...v3.7.3
[3.7.2]: https://github.com/sabbah13/newo-cli/compare/v3.7.1...v3.7.2
[3.7.1]: https://github.com/sabbah13/newo-cli/compare/v3.7.0...v3.7.1
[3.3.0]: https://github.com/sabbah13/newo-cli/compare/v3.2.0...v3.3.0
[3.2.0]: https://github.com/sabbah13/newo-cli/compare/v3.1.0...v3.2.0
[3.1.0]: https://github.com/sabbah13/newo-cli/compare/v3.0.0...v3.1.0
[3.0.0]: https://github.com/sabbah13/newo-cli/compare/v2.0.6...v3.0.0
[3.7.0]: https://github.com/sabbah13/newo-cli/compare/v3.6.2...v3.7.0
[3.6.2]: https://github.com/sabbah13/newo-cli/compare/v3.6.1...v3.6.2
[2.0.6]: https://github.com/sabbah13/newo-cli/compare/v2.0.5...v2.0.6
[2.0.5]: https://github.com/sabbah13/newo-cli/compare/v2.0.4...v2.0.5
[2.0.4]: https://github.com/sabbah13/newo-cli/compare/v2.0.3...v2.0.4
[2.0.3]: https://github.com/sabbah13/newo-cli/compare/v2.0.2...v2.0.3
[2.0.2]: https://github.com/sabbah13/newo-cli/compare/v2.0.1...v2.0.2
[2.0.1]: https://github.com/sabbah13/newo-cli/compare/v2.0.0...v2.0.1
[2.0.0]: https://github.com/sabbah13/newo-cli/compare/v1.8.0...v2.0.0
[1.9.3]: https://github.com/sabbah13/newo-cli/compare/v1.9.2...v1.9.3
[1.9.2]: https://github.com/sabbah13/newo-cli/compare/v1.9.1...v1.9.2
[1.9.1]: https://github.com/sabbah13/newo-cli/compare/v1.9.0...v1.9.1
[1.9.0]: https://github.com/sabbah13/newo-cli/compare/v1.8.0...v1.9.0
[1.8.0]: https://github.com/sabbah13/newo-cli/compare/v1.7.0...v1.8.0
[1.7.3]: https://github.com/sabbah13/newo-cli/compare/v1.7.2...v1.7.3
[1.7.2]: https://github.com/sabbah13/newo-cli/compare/v1.7.1...v1.7.2
[1.7.1]: https://github.com/sabbah13/newo-cli/compare/v1.7.0...v1.7.1
[1.7.0]: https://github.com/sabbah13/newo-cli/compare/v1.6.1...v1.7.0
[1.6.1]: https://github.com/sabbah13/newo-cli/compare/v1.6.0...v1.6.1
[1.6.0]: https://github.com/sabbah13/newo-cli/compare/v1.5.1...v1.6.0
[1.5.2]: https://github.com/sabbah13/newo-cli/compare/v1.5.1...v1.5.2
[1.5.1]: https://github.com/sabbah13/newo-cli/compare/v1.5.0...v1.5.1
[1.5.0]: https://github.com/sabbah13/newo-cli/compare/v1.4.0...v1.5.0
[1.4.0]: https://github.com/sabbah13/newo-cli/compare/v1.2.1...v1.4.0
[1.3.0]: https://github.com/sabbah13/newo-cli/compare/v1.2.1...v1.3.0
[1.2.2]: https://github.com/sabbah13/newo-cli/compare/v1.2.1...v1.2.2
[1.2.1]: https://github.com/sabbah13/newo-cli/releases/tag/v1.2.1