@dforge-core/dforge-mcp 0.2.45 → 0.2.46-next

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to `@dforge-core/dforge-mcp`. This project uses semver-ish
 `0.1.0-rc.N` pre-release tags; the published version is set at publish time via
 the release workflow, so committed `package.json` versions are placeholders.
 
+## Unreleased
+
+**`dforge-1c-import`: porting a 1C infobase.** A fifth skill. It carries the decisions a 1C port turns on, each with the
+measurement that settles it: a register's kind, where a posting takes each value, what to carry, physical columns through
+DBNames, vendor against client. It adds `references/loading.md` (copying the rows: swapped uuid halves, the empty reference
+and the empty date as values in register keys and periods, the year offset, enums by `_EnumOrder`, composite references,
+register state, triggers, dangling references, verification) and `references/print-forms.md` (MXL templates, the print
+procedure, `Строка`/`Формат` in SQL, reproducing 1C's slips, datasets as queries). `scripts/` ships the Python toolkit
+from a real port: it reads the configuration and DBNames from MS SQL without 1C, generates and validates modules, copies and
+reconciles the rows, checks postings and reads print templates, pointed at a port by `DF1C_ROOT` / `DF1C_PROJECT` and
+started from `scripts/project-template/`. `install-skills` installs it with the other four.
+
 ## 0.2.45 — 2026-10-25
 
 **English is the base locale, and it lives in the definitions.** Install never reads

package/README.md

@@ -2,7 +2,7 @@
 
 MCP server for dForge module authoring. Exposes 35 composable tools and the canonical schemas so AI agents (Claude Code, Cursor, Zed, etc.) can drive the full module lifecycle — scaffold → entities → actions → views → security → install — through structured tool calls instead of free-form JSON generation.
 
-Ships with **four Claude Skills** (`skills/`): a router plus one skill per lifecycle stage — design (Phase 0), build (Phases 1-5), and ship (Phase 6). The router directory carries 25 reference files (field types, flags, traits, formulas, DSL, security, etc.) and two annotated example modules.
+Ships with **five Claude Skills** (`skills/`): a router plus one skill per lifecycle stage — design (Phase 0), build (Phases 1-5), and ship (Phase 6) — and `dforge-1c-import` for porting a 1C infobase, with its Python toolkit. The router directory carries 25 reference files (field types, flags, traits, formulas, DSL, security, etc.) and two annotated example modules.
 
 **New here?** Start with **[docs/creating-modules.md](docs/creating-modules.md)** — three ways to scaffold a module (terminal CLI, VS Code sidebar, AI wizard) and when to pick each.
 
@@ -206,6 +206,7 @@ Authoring guidance ships as **four** skills, split by lifecycle stage. Each stag
 | `dforge-module-design` | 0a–0d | Identity, intake guardrails, design doc, pre-scaffold validation. Ends at `readyToScaffold: true`. |
 | `dforge-module-build` | 1–5 | Entities, behavior, views/menus, polish, security. Loading-policy table, core-rules cheat sheet, backtrack protocol. |
 | `dforge-module-ship` | 6 | Validate → pre-pack review → version audit → pack → install-fix loop. |
+| `dforge-1c-import` | — | Porting a 1C:Enterprise infobase: register kinds, posting bindings, what to carry, the row copy and its conversions, print forms. `scripts/` holds the Python toolkit (read the infobase from MS SQL without 1C, generate modules, load, reconcile, check postings, read MXL templates). |
 
 The handoff is deterministic rather than vibes-based: `dforge_module_plan({ action: "check" })` returns `currentPhase` **and** `nextSkill`, derived from the Phase 0 artifacts, the phase ledger in `docs/phase.json`, and evidence read from the module itself (entities without fields, entities without a view, entities without a Select grant).
 

package/package.json

@@ -1,47 +1,49 @@
 {
-  "name": "@dforge-core/dforge-mcp",
-  "version": "0.2.45",
-  "description": "MCP server for dForge module authoring. Exposes 35 scaffold/patch/validate/pack/install tools and schema resources so AI agents (Claude Code, Cursor, Zed) can create and ship dForge modules.",
-  "license": "MIT",
-  "homepage": "https://github.com/iash44/dForge-core",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/dforge-core/dforge-mcp.git"
-  },
-  "bin": {
-    "dforge-mcp": "dist/server.js",
-    "dforge-install-skills": "scripts/install-skills.mjs"
-  },
-  "files": [
-    "dist/",
-    "docs/",
-    "resources/",
-    "skills/",
-    "scripts/install-skills.mjs",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "main": "dist/server.js",
-  "engines": {
-    "node": ">=18"
-  },
-  "dependencies": {
-    "@dforge-core/dforge-cli": "^0.2.36",
-    "@dforge-core/metadata": "^0.0.46",
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "@types/node": "^26.2.0",
-    "tsup": "^8.5.1",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.10"
-  },
-  "scripts": {
-    "build": "tsup",
-    "sync-schemas": "node scripts/vendor-schemas.cjs",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "install-skills": "node scripts/install-skills.mjs"
-  }
-}
+	"name": "@dforge-core/dforge-mcp",
+	"version": "0.2.46-next",
+	"description": "MCP server for dForge module authoring. Exposes 35 scaffold/patch/validate/pack/install tools and schema resources so AI agents (Claude Code, Cursor, Zed) can create and ship dForge modules.",
+	"license": "MIT",
+	"homepage": "https://github.com/iash44/dForge-core",
+	"packageManager": "pnpm@12.14.0+sha512.c18ba6d87993d3d164cb5e8948f32b2c06ee854487e06cd8d86781342fb3e5bb4634367034711e86802baa9c37bea906ce1929ad08d70884c97d801df13389a6",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/dforge-core/dforge-mcp.git"
+	},
+	"bin": {
+		"dforge-mcp": "dist/server.js",
+		"dforge-install-skills": "scripts/install-skills.mjs"
+	},
+	"files": [
+		"dist/",
+		"docs/",
+		"resources/",
+		"skills/",
+		"scripts/install-skills.mjs",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"main": "dist/server.js",
+	"engines": {
+		"node": ">=18"
+	},
+	"scripts": {
+		"build": "tsup",
+		"sync-schemas": "node scripts/vendor-schemas.cjs",
+		"prepublishOnly": "node scripts/vendor-schemas.cjs && tsup",
+		"typecheck": "tsc --noEmit",
+		"test": "vitest run",
+		"install-skills": "node scripts/install-skills.mjs"
+	},
+	"dependencies": {
+		"@dforge-core/dforge-cli": "^0.2.36",
+		"@dforge-core/metadata": "^0.0.46",
+		"@modelcontextprotocol/sdk": "^1.30.0",
+		"zod": "^4.4.3"
+	},
+	"devDependencies": {
+		"@types/node": "^26.2.0",
+		"tsup": "^8.5.1",
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.10"
+	}
+}

package/scripts/install-skills.mjs

@@ -32,6 +32,7 @@ const SKILLS = [
 	["dforge-module-design", "Phase 0  — identity, intake, design, validation"],
 	["dforge-module-build", "Phases 1-5 — entities, behavior, views, security"],
 	["dforge-module-ship", "Phase 6  — validate, pack, install-fix loop"],
+	["dforge-1c-import", "porting a 1C infobase — decisions, loading, print forms,\n                        and the Python toolkit that does the mechanical half"],
 ];
 
 const PKG = "@dforge-core/dforge-mcp";

package/skills/dforge-1c-import/SKILL.md

@@ -0,0 +1,374 @@
+---
+name: dforge-1c-import
+description: How to port a 1C:Enterprise 8 infobase (УТП, УПП, УТ, БП or a configuration built on them) to dForge modules — how to decide a register's kind, where a posting takes each value from, what to carry and what to drop, and how to check every one of those decisions against the data instead of guessing. Use this whenever the work involves a 1C infobase, a 1C configuration, MS SQL tables named _Reference/_Document/_AccumRg/_InfoRg/_AccRg, регистры, проведение, ОбработкаПроведения, Движения, партионный учёт, or migrating a client off 1C onto dForge — including when the user only says "the client's old system" and the tables turn out to be 1C's, and including when they ask only for a piece of it such as "which register kind should this be" or "why does this document write more rows than 1C does". Also covers copying the rows (keys, dates, enums, composite references, empty values, reconciliation) and porting 1C print forms (MXL templates, Строка/Формат, НСтр) to dForge print templates.
+---
+
+# Porting a 1C infobase to dForge
+
+## The stance
+
+A 1C configuration is two things that disagree: what its author **declared** and what its
+documents **do**. The declaration is a proposal, often stale, sometimes never true. The
+movements are the record of what actually happened, thousands of times, for years.
+
+So the rule that makes this work tractable: **when a question can be settled by measuring
+the data, measure it.** Not because the configuration lies on purpose, but because a port
+that copies declarations copies the author's mistakes with them, and a port that copies
+behaviour copies the business.
+
+Two worked cases, both from a real port, both where the obvious source was wrong:
+
+- The accounting policy register pointed at position 0 of a three-value enum and the
+  configuration text would not say which value that was. The write-offs said it in five
+  independent ways in under an hour.
+- A register dimension declared `Строка(10)` held `13.01.2016` in 35,799 rows. The
+  generator read `nvarchar` faithfully — and faithfully carried the author's mistake, a
+  date that does not sort, compare, or match anything a posting would write.
+
+The corollary matters as much: **the volume of 1C code is not the size of the port.** Most
+of a posting handler is the platform's job in dForge — clearing movements, locking,
+`Свернуть`, balance control, re-posting. What you port is the part that decides *which
+value goes where*, and that is usually a few lines inside a handler of hundreds. Read the
+code to learn the requirement; do not transcribe it. Concretely: extract only the
+value-assignment and computation lines (for example, `ЗаполнитьЗначения` targets and
+arithmetic expressions); do not port loop structure, locking calls, or platform
+bookkeeping code.
+
+## What the tools do, and what you decide
+
+Generation and loading are mechanical and should stay that way: unpacking the
+configuration, parsing metadata, mapping types, emitting entities, copying rows,
+reconciling counts. If a port keeps needing hand edits to generated output, the generator
+is wrong, not the output. This skill ships that mechanical half as a toolkit (see **The
+toolkit** below), so a port starts from it rather than from nothing.
+
+What no tool can decide:
+
+| decision | settled by |
+|---|---|
+| which module an object belongs to | the business, plus the dependency graph |
+| a register's **kind** | measuring the register and reading its writers |
+| where a posting takes each value | where the column physically sits |
+| whether to carry a link at all | who reads it |
+| what a strange column type means | the data in it |
+
+The rest of this file is those decisions. Each one has a measurement attached, because a
+decision you can defend with a number survives review and a decision you argued does not.
+
+## Read the posting handler first
+
+Reading a handler before porting it is the cheapest move available and it repeatedly
+answers in minutes what the data leaves ambiguous for days. Do it even when you do not
+intend to port that handler.
+
+What to extract, in order:
+
+1. **Which registers it writes** (`Движения.<name>`), and for each, whether the register
+   belongs to the client or to the vendor configuration. Vendor registers are usually not
+  ported; client registers are the porting unit. A register written by **both** is the
+  awkward case: measure what fraction of its writes are client-originated before deciding
+  anything. A high fraction makes it a client register with vendor writers to account for;
+  a low one usually means the register belongs to machinery you are not carrying, and the
+  client's few writes into it are a question for the client rather than a port.
+2. **Where each movement column is filled from.** `ЗаполнитьЗначения(X, "Col")` after
+   loading a tabular section means: that column comes from the HEADER while the rest come
+   from the lines. This single fact decides the binding (see below) and it is extremely
+   common — in the base measured, 24 of 36 register-writing documents do it.
+3. **Whether it collapses.** `Свернуть(dims, resources)` is not tidying. It means the
+   document's lines can repeat a key and the register holds one row per key. Getting this
+   wrong writes duplicate keys silently.
+4. **What a guard protects.** `Если Стр.Количество <> 0` looks like a condition; measuring
+   how often it has fired tells you how much it is worth, not whether to keep it. A guard
+   that has never fired in years is a poor reason to ask the platform for a new feature —
+   but it is not dead code, because future input can still reach it. Keep the condition
+   where it is cheap (a column, a computed value, a validation on the target), and drop it
+   only when the target genuinely cannot produce the input or the client agrees the rule
+   has changed. Record which of those it was.
+5. **What it computes.** `-(1 - Количество)` is arithmetic, not logic — it becomes a
+   computed column, not code.
+
+**Size does not measure effort, and using it as a proxy is the trap.** A handler's line
+count is mostly vendor accounting the port does not carry: the largest in the base measured
+here was 1,043 lines writing five registers, four of them the vendor's, and its only
+client-owned movement was a status the port already handled. Its client-relevant part was
+smaller and easier than that of handlers a tenth its size.
+
+So scan by size once, to know which handlers you will not read end to end — but do not
+defer the handler itself on that basis, because the client-owned movement buried in a big
+one may be the cheapest thing available. Find the client's registers first and work
+outward from them; order that work by what blocks each handler, so everything unblocked
+ships while the blocked ones wait on one decision each.
+
+### What counts as blocked
+
+A handler is **blocked** when something it needs is not yet decided or not yet available,
+and no amount of writing declarations will change that. Everything else — long, tedious,
+unfamiliar — is work, not a block.
+
+Name the category and the resolver together, because the resolver is what determines when
+it moves:
+
+| category | example | who resolves it |
+|---|---|---|
+| a platform feature that does not exist | a value the binding cannot reach from where it sits | the platform team |
+| a modelling decision not yet made | which register kind, which dimension is missing | you, by measuring |
+| a business question | which valuation method should apply going forward | the client |
+| data that is absent or untrustworthy | a dimension empty across the whole register | investigation, then one of the above |
+
+Two habits make this list useful rather than decorative.
+
+**Keep a count against each category, and re-examine it.** A blocker recorded once tends to
+stay recorded. In the port this skill comes from, the list shrank three times and every
+time *away* from "we need more platform": a collapse the engine already did, a condition
+that was a column rather than a feature, a register declared as the wrong kind. Expect
+mislabelling in that direction — it is the expensive one, because asking for a platform
+feature costs weeks and re-reading your own declaration costs an hour.
+
+**Distinguish "blocked" from "not started".** A handler waiting on a decision is blocked; a
+handler nobody has read is not. The second is much more common early, and conflating them
+makes the port look stuck when it is merely young.
+
+## Choosing a register kind
+
+The decision most likely to be made wrong, because the obvious answer — copy the 1C family
+— is wrong often enough to matter. A 1C `РегистрСведений` is not automatically dForge's
+`kind: "info"`.
+
+One fact governs everything below: **only `balance` aggregates lines by dimension tuple.**
+`info` and `turnover` keep no state and the engine skips the aggregation for both. So if a
+document's lines can repeat a key, `balance` is the only kind that will fold them.
+
+Work through this flow in order. Lines repeat a key when `Свернуть` over the dimensions and
+the measurements (§1) show that repeated document-line tuples become one register row.
+Quantities add; values replace. A price, status, currency, or percentage share is a value;
+a quantity, amount, or count is a quantity.
+
+| Step | Question | Answer | Next step / result |
+|---|---|---|---|
+| 1 | Can the document's lines repeat a key? | No | Go to step 2; every kind remains available. |
+| 1 | Can the document's lines repeat a key? | Yes | Go to step 2. Only `balance` can fold them, but that does not select `balance`: a writer can fold its lines and still replace a snapshot. |
+| 2 | Are the resources quantities or values? | Values; lines do not repeat a key | **`info`**. Done. |
+| 2 | Are the resources quantities or values? | Values; lines repeat a key | **Stop: no kind fits.** The key is incomplete: summing values is meaningless. Find the missing dimension. |
+| 2 | Are the resources quantities or values? | Quantities | Go to step 3. |
+| 3 | Do two documents on one key add or replace? Ask the business and the writer's intent; history (§3) only shows whether the case has occurred. | Add | Go to step 4. |
+| 3 | Do two documents on one key add or replace? | Replace; lines do not repeat a key | **`info`**. Done. |
+| 3 | Do two documents on one key add or replace? | Replace; lines repeat a key | **Stop: no kind fits.** Three options, none free — see the note below. |
+| 4 | Is there a running total to keep? | Yes | **`balance`**. |
+| 4 | Is there a running total to keep? | No; lines do not repeat a key | **`turnover`**: it keeps no total and answers only over an interval. |
+| 4 | Is there a running total to keep? | No; lines repeat a key | **`balance`**: accept the running total because `turnover` would write one row per line. |
+
+**The step 3 "replace, lines repeat" note.** Three options, and the choice belongs in the
+declaration's comment along with the reason: declare `balance` and accept that it adds
+across documents; collapse before posting, which nothing expresses declaratively today; or
+leave it unbound and record it as blocked. Taking the first means **enforcing the
+assumption** — a unique constraint over the dimensions on the state entity, so a second
+writer fails loudly instead of summing. Where you cannot enforce it, say in the comment
+that the semantics are "replace" and the kind is a compromise; the next reader will ask,
+and the honest answer is shorter than the reconstruction.
+
+Past uniqueness does not make adding safe: a future correction can otherwise double a
+period the first time someone re-states it.
+
+One aside that trips people: `info` with a `recorder` is the shape for a 1C register
+subordinate to a регистратор. But subordination is about *who wrote the row*, not about how
+rows combine — do not let it answer step 1.
+
+### When the handler cannot be read
+
+Extraction can come up short, the source can be missing for an object, and a heavily
+customised configuration can defeat a parser that works everywhere else. None of the four
+steps actually depends on the code: the code was only ever the fastest way to see the
+answer, and the rows carry the same answer more slowly.
+
+| step | without the handler |
+|---|---|
+| 1. lines repeat a key? | compare line counts per document against the rows the register holds for that same document — fewer rows than lines **is** the collapse |
+| 2. quantities or values? | the column types and what the values do over time: a figure that repeats unchanged across documents is a value, one that varies per movement is a quantity |
+| 3. add or replace? | history says only whether it has been exercised, so this one still goes to the business — the code would not have answered it either |
+| 4. running total? | whether the register carries a closing or on-hand figure at all, and whether anything reads it as of a date |
+
+Two cautions. A missing handler is worth a moment's suspicion before you route around it:
+if the extraction silently dropped it, other objects are missing too, and finding that out
+now is cheaper than discovering it three registers later. And when you infer rather than
+read, say so in the declaration's comment — an inference that later turns out wrong is much
+easier to unpick when it is labelled as one.
+
+## Where a posting takes each value
+
+A binding that posts from lines reads its values off the line. Any value that belongs to
+the document goes in `headerMap` beside `map`:
+
+```json
+"map":       { "product_id": "product_id", "quantity": "quantity" },
+"headerMap": { "dealer_id": "dealer_id", "period_id": "period_id" },
+"lockedFields": ["dealer_id", "period_id"]
+```
+
+It is explicit rather than a fallback, and that is deliberate: "not on the line, try the
+header" turns a typo into a silent read of an unrelated column, and a dimension that reads
+as null is how a line says it does not participate — so the document would post fewer rows
+than it has lines and say nothing.
+
+Two rules that bite:
+
+- **Every `headerMap` column must be in `lockedFields`.** The posting is keyed by it.
+  Change it under a posted document and reversal looks for a tuple that was never posted
+  to, leaving the old row carrying the quantity forever.
+- **A resource may come from the document only on an `info` register.** Anywhere else four
+  lines would add the document's amount four times.
+
+`headerMap` gives the column **as it stands**. If the 1C handler wrote `НачалоДня(Дата)`
+and the header column is a timestamp, the port needs a day-truncated computed column —
+check whether the time is really there rather than assuming either way, and check whether
+the document already carries a date-typed column that says the same thing.
+
+## Whether to carry something at all
+
+Before porting a column, a link or a mechanism, ask **who reads it**. This is a grep, and
+it settles arguments that otherwise run on aesthetics.
+
+A worked case: a register was subordinate to a регистратор, so every one of its 322,352
+rows knew its document. Carrying that into dForge would have meant declaring a journal.
+The grep found that the only object in the entire infobase naming that register was the
+document that writes it, and the only appearance of the recorder was
+`УдалитьДвиженияРегистратора` — which is unposting, which the platform does on its own. No
+reader, no journal.
+
+The same question retires whole categories. A column nothing writes and nothing reads is
+worse than absent, because the next reader assumes it means something.
+
+## Identify physical columns from metadata, never from cardinality
+
+1C's SQL columns are `_FldNNN`. The temptation, when the metadata is awkward to parse, is
+to identify them by how they behave: the dimension with 86,000 distinct values "must be"
+the batch, the one with 40 "must be" the warehouse. **Do not.** The configuration keys
+every attribute by GUID and `DBNames` maps that GUID to its `_FldNNN`; resolve them that
+way, and use cardinality only as a sanity check on the result.
+
+This is not a style preference. In the port this skill comes from, a cardinality guess
+swapped `СерияНоменклатуры` for `ДокументОприходования` — two reference dimensions of the
+same shape — and five measurements were then computed confidently against the wrong
+column, published, and had to be withdrawn. The failure is silent by construction: every
+query still runs, every number still looks plausible, and nothing downstream objects.
+
+The re-measurement also found what the guess had hidden: the real batch dimension was
+**empty on all 13.8 million rows**, which is a much larger fact about the client's
+accounting than anything the wrong column could have said.
+
+## What a strange column type means
+
+1C's physical types are not the author's intent, and the port reads the physical type. Two
+failure modes, both real:
+
+- **A value parked in the wrong type.** A date in `nvarchar`, a number in a string column.
+  1C coerces silently, so it looks fine in 1C and is useless afterwards. Sweep for it once
+  rather than meeting it one column at a time:
+
+```sql
+-- every text column holding something shaped like a date
+select '<schema>.<table>.<col>', count(*) from <schema>.<table>
+where <col> ~ '^[0-9]{2}\.[0-9]{2}\.[0-9]{4}$'
+```
+
+- **An empty string that is not empty.** 1C writes `''` where a value is absent, so
+  `count(column)` counts it and a column the infobase never filled reads as completely
+  full. Every emptiness check against 1C-sourced data must test for `''`, not `NULL`.
+
+When you retype a column, remember that a date the configuration formatted into a string
+is **not** a 1C date value and must not get the `_YearOffset` correction — that offset is
+how 1C stores a datetime, and nothing stored a datetime there.
+
+## Vendor and client
+
+Configurations built on a vendor's (УТП, УПП, УТ) carry far more code than the client
+wrote. Separate them early — the integrator's own objects almost always carry a lowercase
+prefix before a capital (`мсбЗаказ`, `рзТранспорт`), and everything else is the vendor's.
+If no such convention exists or it is applied inconsistently, do not fall back to "what the
+client's documents touch" — that is circular, since which documents are the client's is the
+question. Compare against the vendor's stock configuration instead: an object absent from
+it is the integrator's, and an object present but altered is a modification worth reading
+before porting either version of it.
+
+**That comparison is often unavailable, and saying so is part of the answer.** The client
+may not hold the distribution, the version they run may not be the version you can get, and
+obtaining it can require exactly the licence this approach is designed not to need. When
+the stock configuration is missing or its version does not match, record the mismatch
+explicitly and treat every conclusion that rests on the comparison as provisional until
+something measured confirms it.
+
+Signals that need no stock configuration, in rough order of strength: the naming
+convention; whether an object holds any data at all (a stock object the client never used
+is not a porting question); which objects the extracted code actually writes to; and the
+language and style of the names themselves. None of these is conclusive alone, which is why
+agreement between several of them is what you are looking for.
+
+**When they disagree, treat the object as the client's until something settles it.** The
+two mistakes are not symmetric: porting a vendor object you did not need costs some work
+that can be dropped later, while dropping a client object loses business logic silently and
+is found months on, by someone who cannot reconstruct it. An object with no prefix but real
+data and real writers is exactly the case this rule exists for — and it is common, because
+integrators abandon their own conventions under deadline.
+
+Two things follow:
+
+- **Port the client's requirements, not the vendor's metadata structure.** The stock
+  configuration is the vendor's intellectual property; what it encodes about the client's
+  business is what you are after.
+- **Do not assume vendor machinery is unused.** Measure which of the client's own objects
+  touch it. A register that looks like pure vendor plumbing may be written by twenty of
+  the client's documents, and dropping it silently removes what those documents are for.
+
+## Order of work
+
+1. Extract and inventory: what exists, how many rows, what is the client's.
+2. Generate and load the plain entities. Reconcile counts and control sums against the
+   infobase before going further — a port that cannot reproduce a count cannot be trusted
+  about anything harder. If counts or control sums do not reconcile, stop and diagnose the
+  generator or loader before proceeding to any handler work; do not proceed with partial
+  or approximate data.
+3. Read the posting handlers. Triage by size, then order the work by what blocks each one.
+4. Declare registers and bind documents, starting where nothing blocks.
+5. Keep a running list of what blocks the rest, with a count against each. The list should
+   shrink in both directions: things the platform must gain, and things that turn out to
+   have been modelled wrong. Expect the second to be more common than it feels.
+
+Keep the generated half and the project half separated by a check, not by convention. The
+generic half is most of the code and lifts to the next infobase; the project half is the
+judgement above, written down.
+
+## The toolkit
+
+Do not write the mechanical half again. `scripts/` in this skill's directory holds the
+Python library that did it on a real port:
+
+- reading the configuration and DBNames straight from MS SQL;
+- parsing the metadata;
+- inventorying registers and handlers;
+- generating and validating modules;
+- copying rows with every conversion in the loader;
+- reconciling counts, sums and foreign keys;
+- posting checks;
+- reading MXL print templates.
+
+`scripts/README.md` gives the setup and the pipeline step by step.
+
+Start a port by copying `scripts/project-template/` into the port's own directory. Set
+`DF1C_ROOT` and `DF1C_PROJECT`, then run `python <skill>/scripts/1c.py --list`. Everything
+this infobase needs goes into the project package, never into `lib/`; `1c.py --boundary`
+checks that. When a tool gets something wrong for a new infobase, fix the library and keep
+the fix general. A second infobase is what turns a port's tooling into a library.
+
+## References
+
+- `references/measurements.md` — the queries behind each decision, ready to adapt
+- `references/loading.md` — copying the rows: the conversions (keys, empty values, the
+  year offset, enums, composite references), register state, triggers, dangling
+  references, verification, incremental re-runs
+- `references/print-forms.md` — porting 1C print forms: reading MXL templates, what the
+  print procedure decides, reproducing 1C's formatting and its slips, datasets as
+  queries, verifying a form
+- `references/environment.md` — the environment traps that cost time repeatedly (Windows
+  bash, Cyrillic in shell commands, 1C physical naming, the year offset)
+- Platform side, from the dForge MCP server: `dforge://reference/registers`,
+  `dforge://reference/data-migration`, `dforge://reference/print-templates`,
+  `dforge://reference/queries`

package/skills/dforge-1c-import/references/environment.md

@@ -0,0 +1,97 @@
+# Environment traps
+
+The things that cost hours the first time and minutes every time after. Written down so
+they cost minutes the first time.
+
+## 1C physical storage
+
+The infobase's SQL tables carry generated names; the configuration maps GUIDs to them.
+
+| prefix | what it is |
+|---|---|
+| `_Reference<N>` | catalog (справочник) |
+| `_Document<N>` | document; its tabular sections are `_Document<N>_VT<M>` |
+| `_InfoRg<N>` | information register; `_InfoRgSL<N>` is its slice-last cache |
+| `_AccumRg<N>` | accumulation register; `_AccumRgT<N>` its totals, `_AccumRgTn<N>` turnovers |
+| `_AccRg<N>` | accounting register |
+| `_Enum<N>` | enumeration; values carry `_EnumOrder`, never their names |
+| `_*ChngR<N>` | change registration for exchange — not the object's own data |
+
+Common columns: `_IDRRef` (16-byte GUID key), `_Period`, `_Active`, `_RecordKind`
+(0 receipt / 1 expense), `_RecorderRRef` + `_RecorderTRef` (the writing document, typed),
+`_LineNo`, `_Fld<N>` for every declared field in declaration order — dimensions first,
+then resources, then attributes.
+
+A field ending `RRef` is a single-type reference; a `_TYPE`/`_RTRef`/`_RRRef` triple is a
+composite one. `_IDRRef` bytes are stored with the halves swapped relative to the printed
+GUID.
+
+**Resolving a `_Fld` number to a name goes through `DBNames`, not through guessing.** The
+configuration keys every attribute by GUID, and `DBNames` holds a `Fld` entry per GUID
+giving its `_FldNNN`; the same file maps `VT` (a tabular section's table) and `LineNo`.
+Parse the object, collect its attributes with their GUIDs, and look each one up. Automate
+it once — everything else depends on it being right.
+
+Field numbers do run in declaration order from the object's base number, dimensions first,
+and distinct-value counts do look suggestive. Use that only to **check** a resolution you
+already made: two reference dimensions of similar shape swap silently, every query still
+runs, and every number downstream is confidently wrong.
+
+## The year offset
+
+1C shifts stored dates by the infobase's `_YearOffset` — commonly 2000, so `4012` in the
+column is 2012, and the empty date `0001-01-01` lands on `2001-01-01` and should become
+NULL.
+
+It applies to **stored datetime columns only**. A date the configuration formatted into a
+string (`НачалоДня(Дата)` assigned to a `Строка(10)` dimension) carries the real year, and
+shifting it as well moves the value back two millennia.
+
+## An empty string is not NULL
+
+1C writes `''` where a value is absent. So `count(column)` counts it, and a column the
+infobase never filled reads as completely full. Sweep for text columns blank on every row
+before trusting any of them; the results split into stock fields the client does not use
+(fine) and columns the port read from the wrong source (not fine).
+
+## Shell: Cyrillic and backticks
+
+When commands are wrapped for execution, Cyrillic characters and backticks in the command
+text can break the wrapper before the command runs — the symptom is `command not found`
+for fragments of your own script, or a syntax error near a Cyrillic word.
+
+The fix that always works: write the script to a file with a file-writing tool, then run
+it by an ASCII-only path. Inside the file, Cyrillic is fine; in a pinch, `\uXXXX` escapes
+in the source keep the command itself ASCII.
+
+## Windows: `bash` is not the bash you want
+
+On Windows, `bash` on PATH resolves to WSL's, which lives in a different filesystem and
+fails with `execvpe(/bin/bash) failed` before reaching your script. Anything that shells
+out to a `.sh` needs Git's bash by full path:
+
+```
+C:\Program Files\Git\bin\bash.exe
+```
+
+This is invisible when working interactively from Git Bash and appears the moment a script
+does the same thing.
+
+## Python on Windows
+
+Output encoding defaults to the system codepage, so Cyrillic output raises
+`UnicodeEncodeError`. Set `PYTHONIOENCODING=utf-8`. When reading and writing files, name
+the encoding explicitly (`io.open(path, encoding="utf-8")`) rather than relying on the
+default.
+
+## Reading the infobase
+
+Read-only, always. Porting needs no writes to the source, and a `SELECT`-only credential
+makes that a property of the connection rather than a promise.
+
+No 1C licence is engaged by reading the SQL tables directly, which is what makes this
+approach available at all — but it also means nothing validates your reading of the
+metadata except the data itself.
+
+Guard the size of exploratory queries: a register of 14 million rows will answer a
+well-scoped question about one month in seconds and an unscoped one in minutes.