Product Manual Mapping

Product Manual Mapping Specification

Overview

The product manual mapping system provides relationships between products and their translated manuals. This enables product detail pages to display links to available Japanese-translated documentation.

Key Concept

A single product can have multiple manuals (e.g., User Manual, Quick Start Guide, Assembly Guide). The relationship is defined at the manual level in the external zmanuals project, then synced to this project as a mapping file.

Architecture

Projects Involved

Data Flow

graph LR
    subgraph zmanuals["zmanuals Project"]
        A["manifest.json"]
        B["manual-registry.ts"]
    end

    subgraph takazudomodular["takazudomodular Project"]
        C["product-manual-mapping.mjs"]
        D["ProductDetailManualNav"]
        E["support/manuals/page.tsx"]
    end

    A -->|"productSlug field"| C
    B -->|"sync via skill"| E
    C -->|"lookup by slug"| D

zmanuals Project Structure

Repository Overview

The zmanuals project is a Next.js static export site that hosts Japanese-translated product manuals. Each manual is a PDF converted to a browsable HTML format.

Repository Location: /Users/takazudo/repos/personal/zmanuals

Directory Structure

zmanuals/
├── lib/
│   ├── manual-registry.ts      # Central registry of all manuals
│   └── types/
│       └── manual.ts           # TypeScript types
├── public/
│   └── [manual-id]/
│       ├── data/
│       │   ├── manifest.json   # Manual metadata
│       │   └── pages.json      # Page content data
│       └── images/             # Page images
└── app/
    └── manuals/
        └── [manual]/           # Dynamic routes

Manual Registry

File: lib/manual-registry.ts

The central registry imports all manual manifests and pages, providing lookup functions:

// Registry structure
const MANUAL_REGISTRY: Record<string, ManualRegistryEntry> = {
  'oxi-e16-manual': {
    manifest: oxiE16ManualManifest,
    pages: oxiE16ManualPages,
  },
  'oxi-e16-quick-start': {
    manifest: oxiE16QuickStartManifest,
    pages: oxiE16QuickStartPages,
  },
  // ... more manuals
};

// Helper functions
export function getManifest(manualId: string): ManualManifest;
export function getPagesData(manualId: string): ManualPagesData;
export function getAvailableManuals(): string[];
export function isValidManual(manualId: string): boolean;
export function getManualTitle(manualId: string): string | undefined;

Manifest JSON Structure

File: public/[manual-id]/data/manifest.json

Each manual has a manifest.json containing metadata:

{
  "title": "OXI E16 Manual",
  "brand": "OXI Instruments",
  "version": "1.0.0",
  "totalPages": 74,
  "contentPages": 68,
  "lastUpdated": "2026-01-11T19:05:44.549Z",
  "updatedAt": "20260112",
  "source": {
    "filename": "OXI E16 - User Manual.pdf",
    "processedAt": "2026-01-11T19:05:37.506Z",
    "imageDPI": 300,
    "imageFormat": "png"
  }
}

Proposed Addition: productSlug

To establish product-manual relationships, add productSlug field to manifest.json:

{
  "title": "OXI E16 Manual",
  "brand": "OXI Instruments",
  "productSlug": "oxi-e16",
  "version": "1.0.0",
  // ... rest of manifest
}

Field Details:

Current Manual Count

As of the last sync, zmanuals contains 32 manuals across these brands:

• OXI Instruments: 4 manuals (oxi-one-mk2, oxi-coral, oxi-e16-manual, oxi-e16-quick-start)
• ADDAC System: 20 manuals
• Weston Precision Audio: 8 manuals

takazudomodular Integration

Product Manual Mapping File

Proposed File: src/data/product-manual-mapping.mjs

This file will be auto-generated from zmanuals manifest data:

/**
 * Product to Manual Mapping
 *
 * Auto-generated from zmanuals project manifests.
 * Do not edit manually - use /update-manual-mapping skill.
 *
 * @generated
 */

const productManualMapping = {
  'oxi-e16': [
    {
      id: 'oxi-e16-manual',
      title: 'OXI E16 Manual',
      href: '/manuals/oxi-e16-manual/'
    },
    {
      id: 'oxi-e16-quick-start',
      title: 'OXI E16: Quick Start',
      href: '/manuals/oxi-e16-quick-start/'
    },
  ],
  'oxi-one-mk2': [
    {
      id: 'oxi-one-mk2',
      title: 'OXI ONE MKII Manual',
      href: '/manuals/oxi-one-mk2/'
    },
  ],
  'oxi-coral': [
    {
      id: 'oxi-coral',
      title: 'OXI Coral Manual',
      href: '/manuals/oxi-coral/'
    },
  ],
  // ... more mappings
};

/**
 * Get manuals for a product by slug
 * @param {string} productSlug - Product slug from product-master-data.mjs
 * @returns {Array<{id: string, title: string, href: string}>} Array of manual info objects
 */
export function getManualsForProduct(productSlug) {
  return productManualMapping[productSlug] || [];
}

/**
 * Check if a product has any manuals
 * @param {string} productSlug - Product slug
 * @returns {boolean}
 */
export function hasManuals(productSlug) {
  return productSlug in productManualMapping &&
         productManualMapping[productSlug].length > 0;
}

export { productManualMapping };

Manual Entry Schema

Each manual entry in the mapping:

Component Usage

The ProductDetailManualNav component will use this mapping:

// components/mdx/product-detail-manual-nav.tsx
import { getManualsForProduct, hasManuals } from '@/src/data/product-manual-mapping.mjs';
import { ArrowRight } from '@/components/svg';

interface ProductDetailManualNavProps {
  slug: string;
}

export function ProductDetailManualNav({ slug }: ProductDetailManualNavProps) {
  const manuals = getManualsForProduct(slug);

  if (manuals.length === 0) {
    return null;
  }

  return (
    <div className="...">
      <h4>翻訳マニュアル</h4>
      <ul>
        {manuals.map((manual) => (
          <li key={manual.id}>
            <a href={manual.href} className="...">
              <ArrowRight className="..." />
              {manual.title}
            </a>
          </li>
        ))}
      </ul>
    </div>
  );
}

Sync Workflow

Environment Configuration

Both sync skills require the ZMANUALS_REPO_PATH environment variable:

# .env
ZMANUALS_REPO_PATH=/Users/takazudo/repos/personal/zmanuals

Skill: sync-product-manual-mapping

The /sync-product-manual-mapping skill generates product-manual-mapping.mjs from zmanuals manifests.

Location: .claude/skills/sync-product-manual-mapping/SKILL.md

Workflow:

1. Read ZMANUALS_REPO_PATH from .env
2. List all directories in ${ZMANUALS_REPO_PATH}/public/
3. Read each manifest.json to get productSlug and title
4. Group by productSlug to create the mapping
5. Generate src/data/product-manual-mapping.mjs with helper functions

Skill: update-manual-list

The /update-manual-list skill syncs the manual listing page (app/support/manuals/page.tsx).

Location: .claude/skills/update-manual-list/SKILL.md

Product Slug Mapping Reference

Current mappings to be added to zmanuals manifests:

URL Structure

Manual URLs

Manuals are served via Netlify redirects:

• Pattern: /manuals/[manual-id]/
• Redirect Target: https://takazudomodular-manuals.netlify.app/manuals/[manual-id]/

Configuration

File: static/_redirects (or netlify.toml)

/manuals/*  https://takazudomodular-manuals.netlify.app/manuals/:splat  200

Related Documentation

• Product Master Data - Product catalog specification
• Product Series - Product grouping system

Implementation Status