Improve onboarding documentation

AGENTS.md

@@ -0,0 +1,73 @@
+# Repository Guidelines
+
+## Quick Links
+
+- `package.json` (commands, settings, contributes)
+- `src/extension.ts` (activation + registration hub)
+- `src/ccs/index.ts` (Consistem fork entrypoints)
+
+## Project Structure & Module Organization
+
+- `src/`: TypeScript source for the VS Code extension.
+  - `src/commands/`, `src/providers/`, `src/explorer/`, `src/api/`, `src/utils/`: feature modules.
+  - `src/test/`: extension integration test harness.
+- `src/ccs/`: **Consistem fork layer** (custom commands/providers/integrations kept isolated to reduce upstream merge conflicts).
+- `syntaxes/` and `language-configuration*.json*`: language grammar + editor configuration for ObjectScript.
+- `snippets/`: VS Code snippet definitions.
+- `webview/`: webview assets used by the extension UI.
+- `images/`: icons and documentation images.
+- `test-fixtures/`: workspace fixtures used by integration tests.
+
+## Consistem Fork Notes (Merge-Safe Customizations)
+
+- Prefer implementing Consistem-only behavior inside `src/ccs/` and wiring it up from `src/extension.ts` (command registration, providers, settings).
+- This fork talks to **two** server surfaces:
+  - Official upstream integration via Atelier (`/api/atelier/...`) for standard features.
+  - Consistem internal SourceControl API under `src/ccs/sourcecontrol/` (default base path: `/api/sourcecontrol/vscode`), derived from the active Atelier connection and optionally overridden via `objectscript.ccs.endpoint`.
+- If you must change upstream-owned modules, keep the diff small and route Consistem logic through `src/ccs/` to make future upstream updates easier.
+
+## Hierarchical Agent Instructions
+
+This repo uses “Hierarchical Agent Instructions”: folders may contain their own `AGENTS.md` with **more specific** rules.
+
+- When working on files under a directory, follow the closest `AGENTS.md` in that directory tree.
+- This repository keeps a minimal, common structure:
+  - Root `AGENTS.md` (general rules and contributor guide)
+  - `src/AGENTS.md` (TypeScript/VS Code extension conventions)
+  - `src/ccs/AGENTS.md` (Consistem fork layer conventions)
+
+## Build, Test, and Development Commands
+
+- `npm install`: installs dependencies (also runs `postinstall` to sync VS Code API typings).
+- `npm run compile`: production build (`webpack` + `tsc`).
+- `npm run webpack-dev`: development bundle in watch mode.
+- `npm run watch`: TypeScript watch build (useful for typechecking).
+- `npm test`: runs integration tests via `@vscode/test-electron` (downloads VS Code and installs dependent extensions).
+- `npm run lint` / `npm run lint-fix`: runs ESLint on `src/**`.
+- `npm run package`: produces a `.vsix` via `vsce package`.
+
+For interactive debugging, use VS Code’s `Run and Debug` launch config (see `.vscode/launch.json`) to start an “Extension Development Host”.
+
+## Dependency Changes
+
+- Prefer reusing existing dependencies; adding new runtime deps increases extension size and supply-chain surface area.
+- When you do add/remove deps, keep `package.json` and `package-lock.json` in sync and ensure `npm run compile` stays clean.
+
+## Coding Style & Naming Conventions
+
+- Indentation: 2 spaces (see `.editorconfig`).
+- Formatting: Prettier settings in `.prettierrc` (e.g., `printWidth: 120`).
+- Linting: ESLint flat config in `eslint.config.mjs`; keep changes lint-clean.
+- Prefer descriptive names; keep VS Code command IDs under the existing `vscode-objectscript.*` namespace.
+
+## Testing Guidelines
+
+- Framework: Mocha (TDD UI) running inside a VS Code test instance.
+- Location/pattern: add tests in `src/test/suite/` using `*.test.ts` naming.
+- Keep tests hermetic: rely on `test-fixtures/` instead of a real server when possible.
+
+## Commit & Pull Request Guidelines
+
+- Commit messages typically use an imperative subject and often include a PR reference, e.g. `Fix unit test failure (#73)`.
+- Work on a branch (not `master`). PRs should include: problem statement, approach, testing notes, and screenshots for UI/webview changes.
+- Keep CI green; governance requires PMC review/approvals (see `GOVERNANCE.md` and `CONTRIBUTING.md`). If a change is user-facing, update `CHANGELOG.md`.

CONTRIBUTING.md

@@ -1,67 +1,73 @@
-# Contributing to the ObjectScript extension for Visual Studio Code
+# Contribuindo para o `vscode-objectscript` (fork Consistem)
 
-## Contributing a pull request
+Este repositório é um fork do `intersystems-community/vscode-objectscript`. As customizações da Consistem devem, sempre que possível, ficar isoladas em `src/ccs/` para reduzir conflitos quando atualizarmos o upstream.
 
-### Prerequisites
+## Pré-requisitos
 
 1. [Node.js](https://nodejs.org/) 18.x
-1. Windows, macOS, or Linux
-1. [Visual Studio Code](https://code.visualstudio.com/)
-1. The following VS Code extensions:
-    - [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
-    - [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
-    - [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig)
+2. Windows, macOS ou Linux
+3. [Visual Studio Code](https://code.visualstudio.com/)
+4. Extensões do VS Code:
+   - [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
+   - [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
+   - [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig)
 
-### Setup
+## Setup
 
-```shell
-git clone https://github.com/intersystems-community/vscode-objectscript
+```sh
+git clone https://github.com/consistem/vscode-objectscript
 cd vscode-objectscript
 npm install
 ```
 
-### Errors and Warnings
+## Fluxo de Desenvolvimento
 
-TypeScript errors and warnings will be displayed in the `PROBLEMS` panel of Visual Studio Code.
+- Abra a pasta do projeto no VS Code.
+- Use `Run and Debug` → `Launch Extension` (ou `Launch Extension Alone`) para abrir um `[Extension Development Host]` e validar as mudanças.
+- Erros/avisos TypeScript aparecem no painel `PROBLEMS`.
 
-### Editing code snippets
+Comandos úteis:
 
-Code snippets are defined in files in the /snippets/ folder:
-
-* objectscript-class.json - snippets for class definition context
-* objectscript.json - snippets for objectscript context 
-* objectscript.json - snippets for consistem objectscript context 
-
-Snippets syntax is described [here](https://code.visualstudio.com/docs/editor/userdefinedsnippets). 
-
-### Run dev build and validate your changes
+```sh
+npm run compile     # build de produção (webpack + tsc)
+npm run webpack-dev # build em watch (webpack)
+npm run watch       # typecheck em watch (tsc)
+npm run lint        # ESLint em src/**
+npm test            # testes de integração (VS Code + Mocha)
+```
 
-To test changes, open the `vscode-objectscript` folder in VSCode.
-Then, open the debug panel by clicking the `Run and Debug` icon on the Activity Bar, select the `Launch Extension`
-option from the top menu, and click start. A new window will launch with the title
-`[Extension Development Host]`. Do your testing here.
+## Snippets
 
-If you want to disable all other extensions when testing in the Extension Development Host, choose the `Launch Extension Alone` option instead.
+Os snippets ficam em `snippets/`:
 
-### Pull requests
+- `snippets/objectscript-class.json`: contexto de definição de classes
+- `snippets/objectscript.json`: ObjectScript (geral)
+- `snippets/consistem-objectscript.json`: snippets específicos do fork Consistem
 
-Work should be done on a unique branch -- not the master branch. Pull requests require the approval of two PMC members, as described in the [Governance document](GOVERNANCE.md). PMC review is often high level, so in addition to that, you should request a review by someone familiar with the technical details of your particular pull request. 
+Referência de sintaxe: https://code.visualstudio.com/docs/editor/userdefinedsnippets
 
-We do expect CI to be passing for a pull request before we will consider merging it. CI executed by pull requests will produce a `vsix` file, which can be downloaded and installed manually to test proposed functionality.
+## Customizações Consistem (src/ccs)
 
-## Beta versions
+- Implementações específicas devem morar em `src/ccs/` (comandos, providers e integrações internas).
+- Conexões internas são derivadas da conexão ativa do Atelier, com override opcional por `objectscript.ccs.endpoint`.
+- Quando uma feature “substitui” comportamento padrão (ex.: F12/Ctrl+Click), mantenha fallback para o comportamento nativo do VS Code quando a resolução interna falhar.
 
-Any change to `master` branch will call CI, which will produce [beta release](https://github.com/intersystems-community/vscode-objectscript/releases), which can be manually installed.
+## Branches, Commits e Pull Requests
 
-## Local Build
+- Trabalhe em uma branch (não faça commit direto em `master`).
+- Branches principais:
+  - `master`: linha principal (CI e releases).
+  - `prerelease`: linha de pré-release (quando aplicável).
+- Commits: siga o padrão do histórico do repositório (assunto imperativo; muitas vezes com referência `(#NN)`).
+- PRs devem incluir: descrição objetiva, motivação, como testar (passos), e screenshots para alterações visuais (webview/UI).
+- O CI precisa estar verde; PRs geram artefatos `.vsix` nos workflows do GitHub Actions para teste manual.
 
-Steps to build the extension on your machine once you've cloned the repo:
+## Build Local (VSIX)
 
-```bash
-> npm install -g vsce
-# Perform the next steps in the vscode-objectscript folder.
-> npm install
-> npm run package
+```sh
+npm install -g vsce
+npm install
+npm run package
 ```
 
-Resulting in a `vscode-objectscript-$VERSION.vsix` file in your `vscode-objectscript` folder.
+Isso gera um arquivo `vscode-objectscript-$VERSION.vsix` na raiz do projeto.

README.md

@@ -1,3 +1,13 @@
+<p align="center">
+  <img alt="Consistem" src="images/logo-consistem-horizontal.png" width="280" />
+</p>
+
+> **Fork Consistem:** esta extensão é um fork do projeto oficial [`intersystems-community/vscode-objectscript`](https://github.com/intersystems-community/vscode-objectscript).
+>
+> Ele preserva todas as funcionalidades do projeto original e adiciona integrações, ajustes e padrões internos adotados pela Consistem, com foco em atender necessidades específicas do nosso ecossistema de desenvolvimento.
+
+---
+
 [![Known Vulnerabilities](https://snyk.io/test/github/intersystems-community/vscode-objectscript/badge.svg)](https://snyk.io/test/github/intersystems-community/vscode-objectscript)
 ![Visual Studio Marketplace Version](https://img.shields.io/visual-studio-marketplace/v/intersystems-community.vscode-objectscript.svg)
 [![](https://img.shields.io/visual-studio-marketplace/i/intersystems-community.vscode-objectscript.svg)](https://marketplace.visualstudio.com/items?itemName=intersystems-community.vscode-objectscript)

src/AGENTS.md

@@ -0,0 +1,44 @@
+# Agent Instructions (src/)
+
+Scope: everything under `src/`.
+
+## Quick Links
+
+- `src/extension.ts` (activation + registration hub)
+- `src/utils/index.ts` (shared utilities + `handleError()`)
+- `src/test/suite/` (integration tests)
+
+## Architecture & Boundaries
+
+- `src/extension.ts` is the main activation/registration hub. New commands/providers should be registered here.
+- Treat `src/ccs/` as the **Consistem customization layer**. Prefer adding new Consistem rules, APIs, and UX there to keep upstream merges clean.
+- Avoid coupling Consistem features deeply into upstream modules; keep adapters thin and move behavior into `src/ccs/`.
+
+## Commands, IDs, and Configuration
+
+- Keep command IDs in the existing namespace:
+  - Upstream: `vscode-objectscript.*`
+  - Consistem: `vscode-objectscript.ccs.*` (category “Consistem” in `package.json`).
+- When you add a new command:
+  1) add it to `package.json` under `contributes.commands` (and keybindings/menus if needed),
+  2) register it in `src/extension.ts`,
+  3) add telemetry event wiring if the surrounding pattern does.
+- When you add/update settings:
+  - define them in `package.json` under `contributes.configuration`,
+  - keep Consistem-specific keys under `objectscript.ccs.*` (see `src/ccs/AGENTS.md`).
+
+## Error Handling & Logging
+
+- Prefer `handleError()` for user-facing error surfacing.
+- Avoid `console.*` for runtime logging; follow the established Output channel / logging utilities patterns.
+- Don’t leak credentials or full URLs with embedded auth in logs.
+
+## Style
+
+- 2-space indentation (see `.editorconfig`), Prettier + ESLint enforced.
+- Match existing patterns (async/await, early returns, explicit typing where it adds clarity).
+
+## Performance & UX
+
+- Providers run frequently; avoid doing network calls per keystroke.
+- Prefer progress notifications (`withProgress`) for operations that may take noticeable time.

src/ccs/AGENTS.md

@@ -0,0 +1,72 @@
+# Agent Instructions (src/ccs/)
+
+Scope: everything under `src/ccs/` (Consistem fork layer).
+
+## Quick Links
+
+- `src/ccs/config/settings.ts` (`objectscript.ccs.*` settings contract)
+- `src/ccs/core/http.ts` (HTTP client factory)
+- `src/ccs/sourcecontrol/routes.ts` (internal API route table)
+
+## Purpose (Keep Merges Easy)
+
+- This directory exists to isolate Consistem-specific behavior from upstream code.
+- Prefer implementing new Consistem rules/features here and exposing them via `src/ccs/index.ts`, with minimal wiring in `src/extension.ts`.
+
+## Ownership & Wiring
+
+- Expose public entrypoints from `src/ccs/index.ts` and keep call sites in `src/extension.ts` small.
+- Commands in this layer use the `vscode-objectscript.ccs.*` namespace and are typically shown under the “Consistem” category in `package.json`.
+- If a CCS feature replaces upstream behavior (ex.: F12 / go to definition), always provide a safe fallback to the default VS Code command when CCS resolution fails.
+
+## Settings Contract (objectscript.ccs.*)
+
+- Settings are read on-demand via `getCcsSettings()` (`src/ccs/config/settings.ts`).
+- Keys live under `objectscript.ccs.*` (ex.: `endpoint`, `requestTimeout`, `debugLogging`, `flags`).
+- Treat these as a stable contract for Consistem users: avoid breaking changes; sanitize inputs in `settings.ts` (not scattered across features).
+
+## Server Integrations (Internal APIs)
+
+- CCS calls are routed through `SourceControlApi` (`src/ccs/sourcecontrol/client.ts`) and the route table in `src/ccs/sourcecontrol/routes.ts`.
+- Default base URL is derived from the active Atelier connection; it can be overridden via `objectscript.ccs.endpoint` (see `src/ccs/config/settings.ts`).
+- Keep new endpoints behind a small `clients/*Client.ts` wrapper and typed response shapes in `src/ccs/core/types.ts`.
+- Treat `src/ccs/sourcecontrol/routes.ts` as the source of truth; if you update routes, update this doc (or remove stale endpoint notes).
+
+### Current Internal Endpoints (as of this fork)
+
+Base path: `GET/POST {baseURL}/api/sourcecontrol/vscode` (see `BASE_PATH` in `src/ccs/sourcecontrol/routes.ts`).
+
+- `POST /resolveContextExpression`
+  - Used by: `vscode-objectscript.ccs.resolveContextExpression` (`src/ccs/commands/contextHelp.ts`)
+  - Behavior: sends routine + selected/line expression; may return preview content and a `textExpression` to insert.
+- `POST /getGlobalDocumentation`
+  - Used by: `vscode-objectscript.ccs.getGlobalDocumentation` (`src/ccs/commands/globalDocumentation.ts`)
+  - Behavior: fetches “global documentation” text for the selection/query.
+- `POST /namespaces/{NAMESPACE}/resolveDefinition`
+  - Used by: F12 / Ctrl+Click path via CCS definition lookup (`src/ccs/features/definitionLookup/*` + `src/ccs/commands/goToDefinitionLocalFirst.ts`)
+  - Behavior: resolves symbols using Consistem’s internal server logic; should fall back to VS Code default when it can’t resolve.
+- `POST /namespaces/{NAMESPACE}/createItem`
+  - Used by: `vscode-objectscript.ccs.createItem` (`src/ccs/commands/createItem.ts`)
+  - Behavior: creates a class/routine on the server and returns a file path to open locally.
+- `POST /namespaces/{NAMESPACE}/unitTests/runUnitTests`
+  - Used by: unit test runner integration (`src/commands/unitTest.ts` via `src/ccs/sourcecontrol/routes.ts`)
+  - Behavior: runs server-side tests and returns structured results/console output.
+- `POST /namespaces/{NAMESPACE}/localizarGatilhos`
+  - Used by: `vscode-objectscript.ccs.locateTriggers` (`src/ccs/commands/locateTriggers.ts`)
+  - Behavior: locates triggers and supports opening returned locations.
+
+## Reliability & UX
+
+- Use `requestTimeout` from `objectscript.ccs` settings and respect VS Code’s `http.proxyStrictSSL`.
+- Prefer non-blocking UX: progress notifications for long calls, graceful fallback when CCS resolution fails (e.g., fall back to VS Code’s default definition).
+- User-facing strings in this layer are typically PT-BR; keep tone consistent and actionable.
+
+## Logging & Errors
+
+- Use `logDebug/logInfo/logWarn/logError` (`src/ccs/core/logging.ts`) instead of ad-hoc output.
+- For errors coming from HTTP calls, surface a short message to the user and log details only when `debugLogging` is enabled.
+
+## HTTP & Security
+
+- Create HTTP clients via `createHttpClient()` (`src/ccs/core/http.ts`); don’t instantiate `axios` directly elsewhere in this folder.
+- Never log credentials, auth headers, or full URLs that could embed secrets.