@javierfrancoleal/docfactory 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 J.Franco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+---
+description: "The professional document factory: consulting-grade techniques + editorial DNA + the reusable docfx.py library."
+kind: "package-bundle"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @javierfrancoleal/docfactory
+
+Created by **J.Franco**.
+
+## Summary
+
+When the model creates professional documents (business plans, one-pagers,
+agreements), this skill applies consulting-grade techniques — boxes that
+never split across pages (cantSplit + keep-next chains), repeating table
+headers, no orphan/widow lines, page numbers, document metadata,
+consistent hyperlinks — plus the Franco Vision editorial DNA (no
+meta-pointers, narrative flow, modest numbers, no over-promising, one
+concept defined once).
+
+## Use
+
+Ask "docfactory" before creating or polishing any Word/PDF document.
+The skill points to the reusable `docfx.py` library (in the plugin
+assets) that implements every technique.
+
+## License
+
+MIT — see the package license field.

package/assets/docfactory.md

@@ -0,0 +1,72 @@
+# Docfactory — the professional document factory
+
+Use this skill whenever a professional document is created or polished
+(Word/PDF: business plans, one-pagers, agreements, guides). Two pillars:
+the consulting techniques and the editorial DNA. Both were validated on
+real documents and are implemented in a reusable library.
+
+## Pillar 1 — The consulting techniques (layout)
+
+1. **Boxes never straddle pages — the sustainable balance** —
+   `cantSplit` on every table row (a row never breaks). SMALL boxes
+   (≤4 rows) also get the keep-next chain, so the whole box moves
+   together. TALL tables do NOT get the chain: they flow across pages
+   with a repeating header (`tblHeader`). Forcing a tall box whole is
+   the mistake that creates giant white gaps — and an orphaned section
+   title means the header chain ends before the table: chain the title
+   AND let tall content flow.
+2. **Table headers repeat** — `tblHeader` on the first row: if a table
+   continues on another page, its header reappears.
+3. **No orphan/widow lines** — `widowControl` on the Normal style and
+   every paragraph.
+4. **Headings stick to their content** — keep-with-next on section
+   labels and titles.
+5. **Page numbers** — a real PAGE field in the footer.
+6. **Document metadata** — core properties (title, author, subject,
+   company) so the file identifies itself in any operating system.
+7. **Hyperlinks** — blue, underlined, external relationships, one per
+   claim.
+8. **Delegable reading guides** — every section names its reader
+   ("À lire par : ...").
+9. **One design language** — Arial, a single accent color, gray
+   hairlines, generous line spacing (1.18).
+10. **Balanced emphasis** — bold only for the essential.
+
+## Pillar 2 — The editorial DNA (writing)
+
+- **No meta-pointers**: never "voir la section X", never "(the sources
+  are in section 2)". If a link proves it, the link proves it.
+- **Narrative flow**: the text reads like a story; nothing is deferred
+  to another part.
+- **Modest numbers**: verify every figure against a public source or
+  mark it "en suspens, à valider". No exaggerated projections.
+- **No over-promising**: never "sans risques" — promise what is real
+  (control, accountability, accompaniment).
+- **One concept defined once**: no repetitions; if a point must
+  resurface, it resurfaces in its exact place, not everywhere.
+- **Human accountability**: the AI prepares; the human decides, signs
+  and assumes — and this is a selling point, not a limitation.
+
+## The library
+
+The plugin assets contain `docfx.py` — a python-docx library that
+implements Pillar 1 (new_doc, header_block, rule, section, para, bullet,
+cite, table3, footer). To use it: copy `docfx.py` into the workspace,
+then in the generator:
+
+```python
+import sys; sys.path.insert(0, ".")
+from docfx import *
+doc = new_doc(title, subject)
+table3(doc, rows, widths, header=("A", "B", "C"))
+footer(doc, "Company line", "Document id · Date")
+```
+
+## Checklist before delivering
+
+1. Every table row has cantSplit + the keep-next chain.
+2. No section header is orphaned at a page bottom.
+3. Page numbers and metadata present.
+4. No "voir la section", no "sans risques", no repeated concepts.
+5. Accents survive copy-paste (explicit font: Arial, fr-CA language).
+6. Every claim links to a verifiable public source.

package/assets/docfx.py

@@ -0,0 +1,174 @@
+# docfx — the Franco Vision document factory.
+# Professional consulting techniques, one reusable library:
+#   · cantSplit + keepNext chains (boxes never straddle pages)
+#   · tblHeader (table headers repeat when a table continues)
+#   · widowControl (no orphan lines at page breaks)
+#   · page numbers (PAGE field) + document core properties
+#   · hyperlinks, hairline rules, delegable section headers
+#   · consistent palette (blue #4D6BFE, grays, Arial, fr-CA)
+import sys
+from docx import Document
+from docx.shared import Pt, Cm, RGBColor
+from docx.enum.text import WD_ALIGN_PARAGRAPH
+from docx.enum.table import WD_TABLE_ALIGNMENT
+from docx.oxml.ns import qn
+from docx.oxml import OxmlElement
+from docx.opc.constants import RELATIONSHIP_TYPE
+
+INK = RGBColor(0x11, 0x18, 0x27)
+MUTED = RGBColor(0x6B, 0x72, 0x80)
+FAINT = RGBColor(0x9C, 0xA3, 0xAF)
+V = RGBColor(0x4D, 0x6B, 0xFE)
+GRAY = RGBColor(0x4B, 0x55, 0x63)
+LOCKUP = "tools/logo-suite/franco-vision-lockup.png"
+FONT = "Arial"
+
+def new_doc(title, subject, margins=(1.4, 1.2, 1.6, 1.6)):
+    """Document with the house style: Arial, fr-CA, margins, core properties."""
+    doc = Document()
+    s = doc.sections[0]
+    s.top_margin, s.bottom_margin, s.left_margin, s.right_margin = (Cm(x) for x in margins)
+    st = doc.styles["Normal"]
+    st.font.name = FONT
+    st.font.size = Pt(9.5)
+    rPr = st.element.get_or_add_rPr()
+    rFonts = rPr.find(qn("w:rFonts"))
+    if rFonts is None:
+        rFonts = OxmlElement("w:rFonts"); rPr.append(rFonts)
+    for attr in ("ascii", "hAnsi", "cs"):
+        rFonts.set(qn("w:" + attr), FONT)
+    lang = OxmlElement("w:lang"); lang.set(qn("w:val"), "fr-CA"); rPr.append(lang)
+    wc = OxmlElement("w:widowControl"); rPr.append(wc)  # no orphan lines
+    cp = doc.core_properties
+    cp.title = title
+    cp.author = "Javier Alejandro FRANCO LEAL"
+    cp.subject = subject
+    cp.company = "Franco Vision inc."
+    return doc
+
+def add_hyperlink(paragraph, text, url, size=9):
+    part = paragraph.part
+    r_id = part.relate_to(url, RELATIONSHIP_TYPE.HYPERLINK, is_external=True)
+    hl = OxmlElement("w:hyperlink"); hl.set(qn("r:id"), r_id)
+    run = OxmlElement("w:r"); rPr = OxmlElement("w:rPr")
+    c = OxmlElement("w:color"); c.set(qn("w:val"), "4D6BFE"); rPr.append(c)
+    u = OxmlElement("w:u"); u.set(qn("w:val"), "single"); rPr.append(u)
+    sz = OxmlElement("w:sz"); sz.set(qn("w:val"), str(int(size * 2))); rPr.append(sz)
+    run.append(rPr)
+    t_el = OxmlElement("w:t"); t_el.text = text; run.append(t_el)
+    hl.append(run); paragraph._p.append(hl)
+
+def rule(doc, color="4D6BFE", sz=6, space_after=8):
+    p = doc.add_paragraph(); pPr = p._p.get_or_add_pPr(); pBdr = OxmlElement("w:pBdr")
+    b = OxmlElement("w:bottom")
+    b.set(qn("w:val"), "single"); b.set(qn("w:sz"), str(sz)); b.set(qn("w:color"), color); b.set(qn("w:space"), "4")
+    pBdr.append(b); pPr.append(pBdr)
+    p.paragraph_format.space_after = Pt(space_after)
+    return p
+
+def para(doc, text="", size=9.5, color=INK, bold=False, align=None, space_after=4, space_before=0, line=1.18, keep_next=False):
+    p = doc.add_paragraph(); r = p.add_run(text)
+    r.font.size = Pt(size); r.font.color.rgb = color; r.bold = bold
+    if align is not None: p.alignment = align
+    pf = p.paragraph_format
+    pf.space_after = Pt(space_after); pf.space_before = Pt(space_before); pf.line_spacing = line
+    pf.keep_with_next = keep_next
+    pPr = p._p.get_or_add_pPr()
+    if pPr.find(qn("w:widowControl")) is None:
+        pPr.append(OxmlElement("w:widowControl"))
+    return p
+
+def section(doc, num, title, audience, size=14):
+    para(doc, "SECTION " + num, size=8, color=V, bold=True, space_before=12, space_after=1, keep_next=True)
+    para(doc, title, size=size, bold=True, space_after=2, keep_next=True)
+    p = doc.add_paragraph()
+    r = p.add_run("À lire par : " + audience)
+    r.font.size = Pt(8.5); r.font.color.rgb = GRAY; r.italic = True
+    p.paragraph_format.space_after = Pt(4)
+    rule(doc, color="E5E7EB", sz=4, space_after=6)
+
+def bullet(doc, lead, rest, size=9.5):
+    p = doc.add_paragraph()
+    r1 = p.add_run("· " + lead); r1.bold = True; r1.font.size = Pt(size); r1.font.color.rgb = INK
+    r2 = p.add_run(rest); r2.font.size = Pt(size); r2.font.color.rgb = MUTED
+    p.paragraph_format.space_after = Pt(3)
+    p.paragraph_format.line_spacing = 1.18
+    return p
+
+def cite(doc, text, url, size=9):
+    p = doc.add_paragraph(); add_hyperlink(p, text, url, size=size)
+    p.paragraph_format.space_after = Pt(2)
+    return p
+
+def shade(cell, hexcolor):
+    tcPr = cell._tc.get_or_add_tcPr()
+    shd = OxmlElement("w:shd"); shd.set(qn("w:val"), "clear"); shd.set(qn("w:fill"), hexcolor)
+    tcPr.append(shd)
+
+def cell_borders(cell, edges, color="E5E7EB", sz=4):
+    tcPr = cell._tc.get_or_add_tcPr(); b = OxmlElement("w:tcBorders")
+    for side in edges:
+        el = OxmlElement("w:" + side)
+        el.set(qn("w:val"), "single"); el.set(qn("w:sz"), str(sz)); el.set(qn("w:color"), color)
+        b.append(el)
+    tcPr.append(b)
+
+def no_split(row):
+    trPr = row._tr.get_or_add_trPr()
+    if trPr.find(qn("w:cantSplit")) is None:
+        trPr.append(OxmlElement("w:cantSplit"))
+
+def keep_together(t):
+    """Chain every row to the next: the whole box moves together, never straddles pages."""
+    for r in t.rows[:-1]:
+        for c in r.cells:
+            for p in c.paragraphs:
+                p.paragraph_format.keep_with_next = True
+
+def header_repeats(t):
+    """The header row repeats when the table continues on the next page."""
+    trPr = t.rows[0]._tr.get_or_add_trPr()
+    if trPr.find(qn("w:tblHeader")) is None:
+        trPr.append(OxmlElement("w:tblHeader"))
+
+def table3(doc, rows, widths=(2.2, 10.0, 5.0), header=("", "", "")):
+    t = doc.add_table(rows=1, cols=3); t.autofit = False
+    no_split(t.rows[0])
+    for i, htxt in enumerate(header):
+        c = t.rows[0].cells[i]; c.width = Cm(widths[i]); shade(c, "F3F4F6")
+        p = c.paragraphs[0]; r = p.add_run(htxt); r.bold = True; r.font.size = Pt(8.5); r.font.color.rgb = MUTED
+        p.paragraph_format.space_before = Pt(2); p.paragraph_format.space_after = Pt(2)
+    for a, b, c3 in rows:
+        rw = t.add_row(); no_split(rw)
+        for i, val in enumerate((a, b, c3)):
+            c = rw.cells[i]; c.width = Cm(widths[i]); cell_borders(c, ["bottom"])
+            p = c.paragraphs[0]; r = p.add_run(val); r.font.size = Pt(9)
+            p.paragraph_format.space_before = Pt(2); p.paragraph_format.space_after = Pt(2)
+            if i == 0: r.bold = True; r.font.color.rgb = V
+            elif i == 2: r.bold = True; r.font.color.rgb = INK
+            else: r.font.color.rgb = INK
+    keep_together(t); header_repeats(t)
+    return t
+
+def header_block(doc, doctype, lockup_width=4.2):
+    t = doc.add_table(rows=1, cols=2); t.alignment = WD_TABLE_ALIGNMENT.CENTER; t.autofit = False
+    t.columns[0].width = Cm(11.0); t.columns[1].width = Cm(6.8)
+    c0, c1 = t.rows[0].cells
+    p0 = c0.paragraphs[0]; p0.add_run().add_picture(LOCKUP, width=Cm(lockup_width))
+    p1 = c1.paragraphs[0]; p1.alignment = WD_ALIGN_PARAGRAPH.RIGHT
+    r4 = p1.add_run(doctype); r4.font.size = Pt(8); r4.bold = True; r4.font.color.rgb = MUTED
+    return t
+
+def footer(doc, text, docid):
+    rule(doc, color="E5E7EB", sz=4, space_after=4)
+    p = doc.add_paragraph(); p.alignment = WD_ALIGN_PARAGRAPH.CENTER
+    r = p.add_run(text + "  ·  Page ")
+    r.font.size = Pt(7.5); r.font.color.rgb = FAINT
+    fld = OxmlElement("w:fldSimple"); fld.set(qn("w:instr"), "PAGE")
+    rr = OxmlElement("w:r"); tt = OxmlElement("w:t"); tt.text = "1"; rr.append(tt); fld.append(rr)
+    p._p.append(fld)
+    p.paragraph_format.space_after = Pt(1)
+    p2 = doc.add_paragraph(); p2.alignment = WD_ALIGN_PARAGRAPH.CENTER
+    r2 = p2.add_run(docid)
+    r2.font.size = Pt(7); r2.font.color.rgb = FAINT
+    p2.paragraph_format.space_after = Pt(0)

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# @javierfrancoleal/docfactory — J.Franco's professional document factory.
+- insert:
+    - id: docfactory
+      name: '@javierfrancoleal/docfactory'

package/icon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <rect width="64" height="64" rx="14" fill="#4D6BFE"/>
+  <rect x="16" y="10" width="32" height="44" rx="3" fill="#ffffff"/>
+  <line x1="22" y1="20" x2="42" y2="20" stroke="#4D6BFE" stroke-width="2.5" stroke-linecap="round"/>
+  <line x1="22" y1="28" x2="42" y2="28" stroke="#4D6BFE" stroke-width="2.5" stroke-linecap="round"/>
+  <line x1="22" y1="36" x2="34" y2="36" stroke="#9CA3AF" stroke-width="2.5" stroke-linecap="round"/>
+  <circle cx="46" cy="46" r="6" fill="#FACC15"/>
+</svg>

package/lib/index.js

@@ -0,0 +1,45 @@
+// @javierfrancoleal/docfactory — an organ of the J.Franco agentic workflow.
+// Created by J.Franco. Registers the docfactory skill provider.
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { BUNDLED_SKILL_RANK } from "@deepseek-ai/dsh-skill";
+
+const PROVIDER_NAME = "javierfrancoleal-docfactory";
+const SKILL_BODY_URL = new URL("../assets/docfactory.md", import.meta.url);
+const RESOURCE_BASE = { kind: "directory", path: fileURLToPath(new URL("../assets/", import.meta.url)) };
+
+const CANDIDATE = {
+  name: "docfactory",
+  description: "The professional document factory of the J.Franco agentic workflow: consulting-grade layout techniques (boxes that never split pages, repeating table headers, no orphan lines, page numbers, metadata) + the editorial DNA (no meta-pointers, narrative flow, modest numbers, no over-promising) + the reusable docfx.py library.",
+  invocation: { modelInvocable: true, userInvocable: true },
+  provider: PROVIDER_NAME,
+  source: "bundled",
+  resourceBase: RESOURCE_BASE,
+  rank: BUNDLED_SKILL_RANK,
+  locator: SKILL_BODY_URL,
+};
+
+const provider = {
+  name: PROVIDER_NAME,
+  list: () => Promise.resolve([CANDIDATE]),
+  async get() {
+    return {
+      name: CANDIDATE.name,
+      description: CANDIDATE.description,
+      invocation: CANDIDATE.invocation,
+      provider: CANDIDATE.provider,
+      source: CANDIDATE.source,
+      resourceBase: RESOURCE_BASE,
+      content: await readFile(SKILL_BODY_URL, "utf8"),
+    };
+  },
+};
+
+const name = "docfactory";
+const inject = ["skills"];
+
+function apply(ctx) {
+  ctx.skills.registerProvider(() => provider);
+}
+
+export { apply, inject, name };

package/locale/ar.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "مصنع المستندات",
+    "description": "تقنيات مستندات احترافية + حمض نووي تحريري لمستندات بمستوى الاستشارات."
+  }
+}

package/locale/de.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Dokumentfabrik",
+    "description": "Professionelle Dokumenttechniken + redaktionelle DNA für Beratungsdokumente."
+  }
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Doc Factory",
+    "description": "Professional document techniques + editorial DNA for consulting-grade documents."
+  }
+}

package/locale/es.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Fábrica de Documentos",
+    "description": "Técnicas profesionales de documentos + ADN editorial para documentos de consultoría."
+  }
+}

package/locale/fr.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Usine à documents",
+    "description": "Techniques professionnelles de documents + ADN éditorial pour des documents de calibre conseil."
+  }
+}

package/locale/it.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Fabbrica di documenti",
+    "description": "Tecniche professionali per documenti + DNA editoriale di livello consulenza."
+  }
+}

package/locale/ja.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "文書ファクトリー",
+    "description": "プロ向け文書技法＋編集DNAでコンサル級の文書を作成します。"
+  }
+}

package/locale/ko.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "문서 팩토리",
+    "description": "전문 문서 기법 + 편집 DNA로 컨설팅급 문서를 만듭니다."
+  }
+}

package/locale/pt.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Fábrica de Documentos",
+    "description": "Técnicas profissionais de documentos + ADN editorial para documentos de consultoria."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "文档工厂",
+    "description": "专业文档技巧 + 编辑 DNA，产出咨询级文档。"
+  }
+}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@javierfrancoleal/docfactory",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "The professional document factory of the J.Franco agentic workflow: consulting-grade techniques (boxes that never split pages, repeating table headers, no orphan lines, page numbers, metadata) + the editorial DNA (no meta-pointers, narrative flow, modest numbers, no over-promising) + a reusable docfx.py library. Created by J.Franco.",
+  "author": "J.Franco",
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "icon": "./icon.svg",
+  "files": [
+    "icon.svg",
+    "locale/*.json",
+    "lib/index.js",
+    "assets",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24",
+    "dsh": ">=0.2.1-rc.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JavierFrancoLeal/jfranco-agentic-suite.git",
+    "directory": "jfranco-docfactory"
+  },
+  "homepage": "https://github.com/JavierFrancoLeal/jfranco-agentic-suite",
+  "keywords": [
+    "deepseek-harness",
+    "agentic-workflow",
+    "super-agent",
+    "documents",
+    "docx",
+    "consulting"
+  ],
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5",
+    "@deepseek-ai/dsh-skill": ">=0.2.1-rc.5"
+  }
+}